001 /*
002 * Copyright 2000-2003 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.security.cert;
027
028 import java.util.Iterator;
029 import java.util.Set;
030
031 /**
032 * An immutable valid policy tree node as defined by the PKIX certification
033 * path validation algorithm.
034 *
035 * <p>One of the outputs of the PKIX certification path validation
036 * algorithm is a valid policy tree, which includes the policies that
037 * were determined to be valid, how this determination was reached,
038 * and any policy qualifiers encountered. This tree is of depth
039 * <i>n</i>, where <i>n</i> is the length of the certification
040 * path that has been validated.
041 *
042 * <p>Most applications will not need to examine the valid policy tree.
043 * They can achieve their policy processing goals by setting the
044 * policy-related parameters in <code>PKIXParameters</code>. However,
045 * the valid policy tree is available for more sophisticated applications,
046 * especially those that process policy qualifiers.
047 *
048 * <p>{@link PKIXCertPathValidatorResult#getPolicyTree()
049 * PKIXCertPathValidatorResult.getPolicyTree} returns the root node of the
050 * valid policy tree. The tree can be traversed using the
051 * {@link #getChildren getChildren} and {@link #getParent getParent} methods.
052 * Data about a particular node can be retrieved using other methods of
053 * <code>PolicyNode</code>.
054 *
055 * <p><b>Concurrent Access</b>
056 * <p>All <code>PolicyNode</code> objects must be immutable and
057 * thread-safe. Multiple threads may concurrently invoke the methods defined
058 * in this class on a single <code>PolicyNode</code> object (or more than one)
059 * with no ill effects. This stipulation applies to all public fields and
060 * methods of this class and any added or overridden by subclasses.
061 *
062 * @version 1.17 07/30/07
063 * @since 1.4
064 * @author Sean Mullan
065 */
066 public interface PolicyNode {
067
068 /**
069 * Returns the parent of this node, or <code>null</code> if this is the
070 * root node.
071 *
072 * @return the parent of this node, or <code>null</code> if this is the
073 * root node
074 */
075 PolicyNode getParent();
076
077 /**
078 * Returns an iterator over the children of this node. Any attempts to
079 * modify the children of this node through the
080 * <code>Iterator</code>'s remove method must throw an
081 * <code>UnsupportedOperationException</code>.
082 *
083 * @return an iterator over the children of this node
084 */
085 Iterator<? extends PolicyNode> getChildren();
086
087 /**
088 * Returns the depth of this node in the valid policy tree.
089 *
090 * @return the depth of this node (0 for the root node, 1 for its
091 * children, and so on)
092 */
093 int getDepth();
094
095 /**
096 * Returns the valid policy represented by this node.
097 *
098 * @return the <code>String</code> OID of the valid policy
099 * represented by this node. For the root node, this method always returns
100 * the special anyPolicy OID: "2.5.29.32.0".
101 */
102 String getValidPolicy();
103
104 /**
105 * Returns the set of policy qualifiers associated with the
106 * valid policy represented by this node.
107 *
108 * @return an immutable <code>Set</code> of
109 * <code>PolicyQualifierInfo</code>s. For the root node, this
110 * is always an empty <code>Set</code>.
111 */
112 Set<? extends PolicyQualifierInfo> getPolicyQualifiers();
113
114 /**
115 * Returns the set of expected policies that would satisfy this
116 * node's valid policy in the next certificate to be processed.
117 *
118 * @return an immutable <code>Set</code> of expected policy
119 * <code>String</code> OIDs. For the root node, this method
120 * always returns a <code>Set</code> with one element, the
121 * special anyPolicy OID: "2.5.29.32.0".
122 */
123 Set<String> getExpectedPolicies();
124
125 /**
126 * Returns the criticality indicator of the certificate policy extension
127 * in the most recently processed certificate.
128 *
129 * @return <code>true</code> if extension marked critical,
130 * <code>false</code> otherwise. For the root node, <code>false</code>
131 * is always returned.
132 */
133 boolean isCritical();
134 }
|