View Javadoc
1   /*
2    * Copyright (c) 1996, 2013, 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;
27  
28  import javax.security.auth.Subject;
29  
30  /**
31   * This interface represents the abstract notion of a principal, which
32   * can be used to represent any entity, such as an individual, a
33   * corporation, and a login id.
34   *
35   * @see java.security.cert.X509Certificate
36   *
37   * @author Li Gong
38   */
39  public interface Principal {
40  
41      /**
42       * Compares this principal to the specified object.  Returns true
43       * if the object passed in matches the principal represented by
44       * the implementation of this interface.
45       *
46       * @param another principal to compare with.
47       *
48       * @return true if the principal passed in is the same as that
49       * encapsulated by this principal, and false otherwise.
50       */
51      public boolean equals(Object another);
52  
53      /**
54       * Returns a string representation of this principal.
55       *
56       * @return a string representation of this principal.
57       */
58      public String toString();
59  
60      /**
61       * Returns a hashcode for this principal.
62       *
63       * @return a hashcode for this principal.
64       */
65      public int hashCode();
66  
67      /**
68       * Returns the name of this principal.
69       *
70       * @return the name of this principal.
71       */
72      public String getName();
73  
74      /**
75       * Returns true if the specified subject is implied by this principal.
76       *
77       * <p>The default implementation of this method returns true if
78       * {@code subject} is non-null and contains at least one principal that
79       * is equal to this principal.
80       *
81       * <p>Subclasses may override this with a different implementation, if
82       * necessary.
83       *
84       * @param subject the {@code Subject}
85       * @return true if {@code subject} is non-null and is
86       *              implied by this principal, or false otherwise.
87       * @since 1.8
88       */
89      public default boolean implies(Subject subject) {
90          if (subject == null)
91              return false;
92          return subject.getPrincipals().contains(this);
93      }
94  }