1/*
2 *  Licensed to the Apache Software Foundation (ASF) under one or more
3 *  contributor license agreements.  See the NOTICE file distributed with
4 *  this work for additional information regarding copyright ownership.
5 *  The ASF licenses this file to You under the Apache License, Version 2.0
6 *  (the "License"); you may not use this file except in compliance with
7 *  the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 *  Unless required by applicable law or agreed to in writing, software
12 *  distributed under the License is distributed on an "AS IS" BASIS,
13 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 *  See the License for the specific language governing permissions and
15 *  limitations under the License.
16 */
17
18package java.security;
19
20import java.util.Enumeration;
21
22
23/**
24 * {@code IdentityScope} represents a scope for {@link Identity} objects.
25 *
26 * @deprecated The functionality of this class has been replace by
27 *             {@link Principal}, {@link KeyStore} and the {@code
28 *             java.security.cert} package.
29 */
30@Deprecated
31public abstract class IdentityScope extends Identity {
32
33    private static final long serialVersionUID = -2337346281189773310L;
34
35    // systemScope holds reference to the current system scope
36    private static IdentityScope systemScope;
37
38    /**
39     * Constructs a new instance of {@code IdentityScope}.
40     */
41    protected IdentityScope() {
42    }
43
44    /**
45     * Constructs a new instance of {@code IdentityScope} with the specified
46     * name.
47     *
48     * @param name
49     *            the name of this {@code IdentityScope}.
50     */
51    public IdentityScope(String name) {
52        super(name);
53    }
54
55    /**
56     * Constructs a new instance of {@code IdentityScope} with the specified
57     * name and the specified scope.
58     *
59     * @param name
60     *            the name of this {@code IdentityScope}.
61     * @param scope
62     *            the scope of this {@code IdentityScope}.
63     * @throws KeyManagementException
64     *             if an identity with the same key already exists.
65     */
66    public IdentityScope(String name, IdentityScope scope)
67            throws KeyManagementException {
68        super(name, scope);
69    }
70
71    /**
72     * Returns the system's scope.
73     *
74     * @return the system's scope.
75     */
76    public static IdentityScope getSystemScope() {
77        /*
78         * Test shows that the implementation class name is read from security property
79         * "system.scope", and the class is only loaded from boot classpath. No default
80         * implementation as fallback, i.e., return null if fails to init an instance.
81         */
82        if (systemScope == null) {
83            String className = Security.getProperty("system.scope");
84            if(className != null){
85                try {
86                    systemScope = (IdentityScope) Class.forName(className).newInstance();
87                } catch (Exception e) {
88                    e.printStackTrace();
89                }
90            }
91        }
92        return systemScope;
93    }
94
95    /**
96     * Sets the system's scope.
97     *
98     * @param scope
99     *            the scope to set.
100     */
101    protected static void setSystemScope(IdentityScope scope) {
102        systemScope = scope;
103    }
104
105    /**
106     * Returns the number of {@code Identity} objects in this scope.
107     *
108     * @return the number of {@code Identity} objects in this scope.
109     */
110    public abstract int size();
111
112    /**
113     * Returns the {@code Identity} with the specified name or {@code null} if
114     * no {@code Identity} with the specified name is present in this scope.
115     *
116     * @param name
117     *            the name of the {@code Identity} to be returned.
118     * @return the {@code Identity} with the specified name or {@code null} if
119     *         not present.
120     */
121    public abstract Identity getIdentity(String name);
122
123    /**
124     * Returns the {@code Identity} with the name of the specified principal or
125     * {@code null} if no {@code Identity} with the name of the specified
126     * principal is present in this scope.
127     *
128     * @param principal
129     *            the {@code Principal} whose name is used to lookup the {@code
130     *            Identity} to be returned.
131     * @return the {@code Identity} with the specified name or {@code null} if
132     *         not present.
133     */
134    public Identity getIdentity(Principal principal) {
135        return getIdentity(principal.getName());
136    }
137
138    /**
139     * Returns the {@code Identity} which is associated with the specified key
140     * or {@code null} if no {@code Identity} associated with the specified key
141     * is present in this scope.
142     *
143     * @param key
144     *            the {@code PublicKey} of the {@code Identity} to be returned.
145     * @return the {@code Identity} associated with the specified key or {@code
146     *         null} if not present.
147     */
148    public abstract Identity getIdentity(PublicKey key);
149
150    /**
151     * Adds an {@code Identity} to this {@code IdentityScope}.
152     *
153     * @param identity
154     *            the {@code Identity} to be added.
155     * @throws KeyManagementException
156     *             if the specified {@code Identity} is invalid or an identity
157     *             with the same key already exists.
158     */
159    public abstract void addIdentity(Identity identity)
160            throws KeyManagementException;
161
162    /**
163     * Removes an {@code Identity} from this {@code IdentityScope}.
164     *
165     * @param identity
166     *            the {@code Identity} to be removed.
167     * @throws KeyManagementException
168     *             if the {@code Identity} is not present in this scope.
169     */
170    public abstract void removeIdentity(Identity identity)
171            throws KeyManagementException;
172
173    /**
174     * Returns an {@code Enumeration} over the {@code Identity} objects in this
175     * {@code IdentityScope}.
176     *
177     * @return an {@code Enumeration} over the {@code Identity} objects in this
178     *         {@code IdentityScope}.
179     */
180    public abstract Enumeration<Identity> identities();
181
182    /**
183     * Returns a string containing a concise, human-readable description of this
184     * {@code IdentityScope}.
185     *
186     * @return a printable representation for this {@code IdentityScope}.
187     */
188    @Override
189    public String toString() {
190        return new StringBuilder(super.toString())
191                .append("[").append(size()).append("]").toString();
192    }
193}
194