libjava/java/security/IdentityScope.java

   1 /* IdentityScope.java --- IdentityScope Class
   2    Copyright (C) 1999, 2003, Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38 package java.security;
  39
  40 import java.util.Enumeration;
  41
  42 /**
  43  * <p>This class represents a scope for identities. It is an Identity itself,
  44  * and therefore has a name and can have a scope. It can also optionally have a
  45  * public key and associated certificates.</p>
  46  *
  47  * <p>An <code>IdentityScope</code> can contain {@link Identity} objects of all
  48  * kinds, including {@link Signer}s. All types of <code>Identity</code> objects
  49  * can be retrieved, added, and removed using the same methods. Note that it is
  50  * possible, and in fact expected, that different types of identity scopes will
  51  * apply different policies for their various operations on the various types of
  52  * Identities.</p>
  53  *
  54  * <p>There is a one-to-one mapping between keys and identities, and there can
  55  * only be one copy of one key per scope. For example, suppose Acme Software,
  56  * Inc is a software publisher known to a user. Suppose it is an <i>Identity</i>,
  57  * that is, it has a public key, and a set of associated certificates. It is
  58  * named in the scope using the name "Acme Software". No other named <i>Identity
  59  * </i> in the scope has the same public key. Of course, none has the same name
  60  * as well.</p>
  61  *
  62  * @author Mark Benvenuto
  63  * @see Identity
  64  * @see Signer
  65  * @see Principal
  66  * @see Key
  67  * @deprecated This class is no longer used. Its functionality has been replaced
  68  * by <code>java.security.KeyStore</code>, the <code>java.security.cert</code>
  69  * package, and <code>java.security.Principal</code>.
  70  */
  71 public abstract class IdentityScope extends Identity
  72 {
  73   private static final long serialVersionUID = -2337346281189773310L;
  74   private static IdentityScope systemScope = null;
  75
  76   /**
  77    * This constructor is used for serialization only and should not be used by
  78    * subclasses.
  79    */
  80   protected IdentityScope()
  81   {
  82     super();
  83   }
  84
  85   /**
  86    * Constructs a new identity scope with the specified name.
  87    *
  88    * @param name the scope name.
  89    */
  90   public IdentityScope(String name)
  91   {
  92     super(name);
  93   }
  94
  95   /**
  96    * Constructs a new identity scope with the specified name and scope.
  97    *
  98    * @param name the scope name.
  99    * @param scope the scope for the new identity scope.
 100    * @throws KeyManagementException if there is already an identity with the
 101    * same name in the scope.
 102    */
 103   public IdentityScope(String name, IdentityScope scope)
 104     throws KeyManagementException
 105   {
 106     super(name, scope);
 107   }
 108
 109   /**
 110    * Returns the system's identity scope.
 111    *
 112    * @return the system's identity scope.
 113    * @see #setSystemScope(IdentityScope)
 114    */
 115   public static IdentityScope getSystemScope()
 116   {
 117     if (systemScope == null)
 118       {
 119         //Load it
 120         //systemScope;
 121       }
 122     return systemScope;
 123   }
 124
 125   /**
 126    * <p>Sets the system's identity scope.</p>
 127    *
 128    * <p>First, if there is a security manager, its <code>checkSecurityAccess()
 129    * </code> method is called with <code>"setSystemScope"</code> as its argument
 130    * to see if it's ok to set the identity scope.</p>
 131    *
 132    * @param scope the scope to set.
 133    * @throws SecurityException if a security manager exists and its
 134    * <code>checkSecurityAccess()<code> method doesn't allow setting the
 135    * identity scope.
 136    * @see #getSystemScope()
 137    * @see SecurityManager#checkSecurityAccess(String)
 138    */
 139   protected static void setSystemScope(IdentityScope scope)
 140   {
 141     SecurityManager sm = System.getSecurityManager();
 142     if (sm != null)
 143       sm.checkSecurityAccess("setSystemScope");
 144
 145     systemScope = scope;
 146   }
 147
 148   /**
 149    * Returns the number of identities within this identity scope.
 150    *
 151    * @return the number of identities within this identity scope.
 152    */
 153   public abstract int size();
 154
 155   /**
 156    * Returns the identity in this scope with the specified name (if any).
 157    *
 158    * @param name the name of the identity to be retrieved.
 159    * @return the identity named name, or <code>null</code> if there are no
 160    * identities named name in this scope.
 161    */
 162   public abstract Identity getIdentity(String name);
 163
 164   /**
 165    * Retrieves the identity whose name is the same as that of the specified
 166    * principal. (Note: <code>Identity</code> implements <code>Principal</code>.)
 167    *
 168    * @param principal the principal corresponding to the identity to be
 169    * retrieved.
 170    * @return the identity whose name is the same as that of the principal, or
 171    * <code>null</code> if there are no identities of the same name in this scope.
 172    */
 173   public Identity getIdentity(Principal principal)
 174   {
 175     return getIdentity(principal.getName());
 176   }
 177
 178   /**
 179    * Retrieves the identity with the specified public key.
 180    *
 181    * @param key the public key for the identity to be returned.
 182    * @return the identity with the given key, or <code>null</code> if there are
 183    * no identities in this scope with that key.
 184    */
 185   public abstract Identity getIdentity(PublicKey key);
 186
 187   /**
 188    * Adds an identity to this identity scope.
 189    *
 190    * @param identity the identity to be added.
 191    * @throws KeyManagementException if the identity is not valid, a name
 192    * conflict occurs, another identity has the same public key as the identity
 193    * being added, or another exception occurs.
 194    */
 195   public abstract void addIdentity(Identity identity)
 196     throws KeyManagementException;
 197
 198   /**
 199    * Removes an identity from this identity scope.
 200    *
 201    * @param identity the identity to be removed.
 202    * @throws KeyManagementException if the identity is missing, or another
 203    * exception occurs.
 204    */
 205   public abstract void removeIdentity(Identity identity)
 206     throws KeyManagementException;
 207
 208   /**
 209    * Returns an enumeration of all identities in this identity scope.
 210    *
 211    * @return an enumeration of all identities in this identity scope.
 212    */
 213   public abstract Enumeration identities();
 214
 215   /**
 216    * Returns a string representation of this identity scope, including its name,
 217    * its scope name, and the number of identities in this identity scope.
 218    *
 219    * @return a string representation of this identity scope.
 220    * @see SecurityManager#checkSecurityAccess(String)
 221    */
 222   public String toString()
 223   {
 224     return (super.getName() + " " + super.getScope().getName() + " " + size());
 225   }
 226 }