1 /*
   2  * Copyright (c) 2000, 2003, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.security.cert;
  27 
  28 import java.util.Iterator;
  29 import java.util.Set;
  30 
  31 /**
  32  * An immutable valid policy tree node as defined by the PKIX certification
  33  * path validation algorithm.
  34  *
  35  * <p>One of the outputs of the PKIX certification path validation
  36  * algorithm is a valid policy tree, which includes the policies that
  37  * were determined to be valid, how this determination was reached,
  38  * and any policy qualifiers encountered. This tree is of depth
  39  * <i>n</i>, where <i>n</i> is the length of the certification
  40  * path that has been validated.
  41  *
  42  * <p>Most applications will not need to examine the valid policy tree.
  43  * They can achieve their policy processing goals by setting the
  44  * policy-related parameters in <code>PKIXParameters</code>. However,
  45  * the valid policy tree is available for more sophisticated applications,
  46  * especially those that process policy qualifiers.
  47  *
  48  * <p>{@link PKIXCertPathValidatorResult#getPolicyTree()
  49  * PKIXCertPathValidatorResult.getPolicyTree} returns the root node of the
  50  * valid policy tree. The tree can be traversed using the
  51  * {@link #getChildren getChildren} and {@link #getParent getParent} methods.
  52  * Data about a particular node can be retrieved using other methods of
  53  * <code>PolicyNode</code>.
  54  *
  55  * <p><b>Concurrent Access</b>
  56  * <p>All <code>PolicyNode</code> objects must be immutable and
  57  * thread-safe. Multiple threads may concurrently invoke the methods defined
  58  * in this class on a single <code>PolicyNode</code> object (or more than one)
  59  * with no ill effects. This stipulation applies to all public fields and
  60  * methods of this class and any added or overridden by subclasses.
  61  *
  62  * @since       1.4
  63  * @author      Sean Mullan
  64  */
  65 public interface PolicyNode {
  66 
  67     /**
  68      * Returns the parent of this node, or <code>null</code> if this is the
  69      * root node.
  70      *
  71      * @return the parent of this node, or <code>null</code> if this is the
  72      * root node
  73      */
  74     PolicyNode getParent();
  75 
  76     /**
  77      * Returns an iterator over the children of this node. Any attempts to
  78      * modify the children of this node through the
  79      * <code>Iterator</code>'s remove method must throw an
  80      * <code>UnsupportedOperationException</code>.
  81      *
  82      * @return an iterator over the children of this node
  83      */
  84     Iterator<? extends PolicyNode> getChildren();
  85 
  86     /**
  87      * Returns the depth of this node in the valid policy tree.
  88      *
  89      * @return the depth of this node (0 for the root node, 1 for its
  90      * children, and so on)
  91      */
  92     int getDepth();
  93 
  94     /**
  95      * Returns the valid policy represented by this node.
  96      *
  97      * @return the <code>String</code> OID of the valid policy
  98      * represented by this node. For the root node, this method always returns
  99      * the special anyPolicy OID: "2.5.29.32.0".
 100      */
 101     String getValidPolicy();
 102 
 103     /**
 104      * Returns the set of policy qualifiers associated with the
 105      * valid policy represented by this node.
 106      *
 107      * @return an immutable <code>Set</code> of
 108      * <code>PolicyQualifierInfo</code>s. For the root node, this
 109      * is always an empty <code>Set</code>.
 110      */
 111     Set<? extends PolicyQualifierInfo> getPolicyQualifiers();
 112 
 113     /**
 114      * Returns the set of expected policies that would satisfy this
 115      * node's valid policy in the next certificate to be processed.
 116      *
 117      * @return an immutable <code>Set</code> of expected policy
 118      * <code>String</code> OIDs. For the root node, this method
 119      * always returns a <code>Set</code> with one element, the
 120      * special anyPolicy OID: "2.5.29.32.0".
 121      */
 122     Set<String> getExpectedPolicies();
 123 
 124     /**
 125      * Returns the criticality indicator of the certificate policy extension
 126      * in the most recently processed certificate.
 127      *
 128      * @return <code>true</code> if extension marked critical,
 129      * <code>false</code> otherwise. For the root node, <code>false</code>
 130      * is always returned.
 131      */
 132     boolean isCritical();
 133 }