AlgorithmParameters


1   /*
2    * @(#)AlgorithmParameters.java 1.24 04/05/05
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7    
8   package java.security;
9   
10  import java.io.*;
11  import java.security.spec.AlgorithmParameterSpec  ;
12  import java.security.spec.InvalidParameterSpecException  ;
13  
14  /**
15   * This class is used as an opaque representation of cryptographic parameters.
16   * 
17   * <p>An <code>AlgorithmParameters</code> object for managing the parameters
18   * for a particular algorithm can be obtained by
19   * calling one of the <code>getInstance</code> factory methods
20   * (static methods that return instances of a given class).
21   * 
22   * <p>There are two ways to request such an implementation: by
23   * specifying either just an algorithm name, or both an algorithm name
24   * and a package provider. 
25   * 
26   * <ul>
27   *
28   * <li>If just an algorithm name is specified, the system will
29   * determine if there is an AlgorithmParameters
30   * implementation for the algorithm requested
31   * available in the environment, and if there is more than one, if
32   * there is a preferred one.
33   * 
34   * <li>If both an algorithm name and a package provider are specified,
35   * the system will determine if there is an implementation 
36   * in the package requested, and throw an exception if there
37   * is not.
38   * 
39   * </ul>
40   * 
41   * <p>Once an <code>AlgorithmParameters</code> object is returned, it must be
42   * initialized via a call to <code>init</code>, using an appropriate parameter
43   * specification or parameter encoding.
44   *
45   * <p>A transparent parameter specification is obtained from an
46   * <code>AlgorithmParameters</code> object via a call to
47   * <code>getParameterSpec</code>, and a byte encoding of the parameters is
48   * obtained via a call to <code>getEncoded</code>.
49   *
50   * @author Jan Luehe
51   *
52   * @version 1.24, 05/05/04
53   *
54   * @see java.security.spec.AlgorithmParameterSpec
55   * @see java.security.spec.DSAParameterSpec
56   * @see KeyPairGenerator
57   *
58   * @since 1.2
59   */
60  
61  public class AlgorithmParameters {
62  
63      // The provider
64      private Provider   provider;
65  
66      // The provider implementation (delegate)
67      private AlgorithmParametersSpi   paramSpi;
68  
69      // The algorithm
70      private String   algorithm;
71  
72      // Has this object been initialized?
73      private boolean initialized = false;
74  
75      /**
76       * Creates an AlgorithmParameters object.
77       *
78       * @param paramSpi the delegate
79       * @param provider the provider
80       * @param algorithm the algorithm
81       */
82      protected AlgorithmParameters(AlgorithmParametersSpi   paramSpi,
83                    Provider   provider, String   algorithm)
84      {
85      this.paramSpi = paramSpi;
86      this.provider = provider;
87      this.algorithm = algorithm;
88      }
89  
90      /**
91       * Returns the name of the algorithm associated with this parameter object.
92       * 
93       * @return the algorithm name.
94       */
95      public final String   getAlgorithm() {
96          return this.algorithm;
97      }
98  
99      /**
100      * Generates a parameter object for the specified algorithm.
101      *
102      * <p>If the default provider package provides an implementation of the
103      * requested algorithm, an instance of AlgorithmParameters containing that
104      * implementation is returned.
105      * If the algorithm is not available in the default 
106      * package, other packages are searched.
107      *
108      * <p>The returned parameter object must be initialized via a call to
109      * <code>init</code>, using an appropriate parameter specification or
110      * parameter encoding.
111      *
112      * @param algorithm the name of the algorithm requested. 
113      *
114      * @return the new parameter object.
115      *
116      * @exception NoSuchAlgorithmException if the algorithm is
117      * not available in the environment.
118      */
119     public static AlgorithmParameters   getInstance(String   algorithm) 
120     throws NoSuchAlgorithmException   {
121     try {
122         Object  [] objs = Security.getImpl(algorithm, "AlgorithmParameters",
123                          (String  )null);
124         return new AlgorithmParameters  ((AlgorithmParametersSpi  )objs[0],
125                        (Provider  )objs[1],
126                        algorithm);
127     } catch(NoSuchProviderException   e) {
128         throw new NoSuchAlgorithmException  (algorithm + " not found");
129     }
130     }
131 
132     /** 
133      * Generates a parameter object for the specified algorithm, as supplied
134      * by the specified provider, if such an algorithm is available from the
135      * provider.
136      *
137      * <p>The returned parameter object must be initialized via a call to
138      * <code>init</code>, using an appropriate parameter specification or
139      * parameter encoding.
140      *
141      * @param algorithm the name of the algorithm requested.
142      *
143      * @param provider the name of the provider.
144      *
145      * @return the new parameter object.
146      *
147      * @exception NoSuchAlgorithmException if the algorithm is
148      * not available in the package supplied by the requested
149      * provider.
150      *
151      * @exception NoSuchProviderException if the provider is not
152      * available in the environment.
153      *
154      * @exception IllegalArgumentException if the provider name is null
155      * or empty. 
156      * 
157      * @see Provider 
158      */
159     public static AlgorithmParameters   getInstance(String   algorithm,
160                           String   provider)
161     throws NoSuchAlgorithmException  , NoSuchProviderException  
162     {
163     if (provider == null || provider.length() == 0)
164         throw new IllegalArgumentException  ("missing provider");
165     Object  [] objs = Security.getImpl(algorithm, "AlgorithmParameters",
166                      provider);
167     return new AlgorithmParameters  ((AlgorithmParametersSpi  )objs[0],
168                        (Provider  )objs[1],
169                        algorithm);
170     }
171 
172     /** 
173      * Generates a parameter object for the specified algorithm, as supplied
174      * by the specified provider, if such an algorithm is available from the
175      * provider. Note: the <code>provider</code> doesn't have to be registered.
176      *
177      * <p>The returned parameter object must be initialized via a call to
178      * <code>init</code>, using an appropriate parameter specification or
179      * parameter encoding.
180      *
181      * @param algorithm the name of the algorithm requested.
182      *
183      * @param provider the name of the provider.
184      *
185      * @return the new parameter object.
186      *
187      * @exception NoSuchAlgorithmException if the algorithm is
188      * not available in the package supplied by the requested
189      * provider.
190      *
191      * @exception IllegalArgumentException if the <code>provider</code> is
192      * null.
193      *
194      * @see Provider
195      *
196      * @since 1.4
197      */
198     public static AlgorithmParameters   getInstance(String   algorithm,
199                           Provider   provider)
200     throws NoSuchAlgorithmException  
201     {
202     if (provider == null)
203         throw new IllegalArgumentException  ("missing provider");
204     Object  [] objs = Security.getImpl(algorithm, "AlgorithmParameters",
205                      provider);
206     return new AlgorithmParameters  ((AlgorithmParametersSpi  )objs[0],
207                        (Provider  )objs[1],
208                        algorithm);
209     }
210 
211     /** 
212      * Returns the provider of this parameter object.
213      * 
214      * @return the provider of this parameter object
215      */
216     public final Provider   getProvider() {
217     return this.provider;
218     }
219 
220     /**
221      * Initializes this parameter object using the parameters 
222      * specified in <code>paramSpec</code>.
223      *
224      * @param paramSpec the parameter specification.
225      *
226      * @exception InvalidParameterSpecException if the given parameter
227      * specification is inappropriate for the initialization of this parameter
228      * object, or if this parameter object has already been initialized.
229      */
230     public final void init(AlgorithmParameterSpec   paramSpec) 
231     throws InvalidParameterSpecException  
232     {
233     if (this.initialized)
234         throw new InvalidParameterSpecException  ("already initialized");
235     paramSpi.engineInit(paramSpec);
236     this.initialized = true;
237     }
238 
239     /**
240      * Imports the specified parameters and decodes them according to the 
241      * primary decoding format for parameters. The primary decoding
242      * format for parameters is ASN.1, if an ASN.1 specification for this type
243      * of parameters exists.
244      *
245      * @param params the encoded parameters.
246      *
247      * @exception IOException on decoding errors, or if this parameter object
248      * has already been initialized.
249      */
250     public final void init(byte[] params) throws IOException {
251     if (this.initialized)
252         throw new IOException("already initialized");
253     paramSpi.engineInit(params);
254     this.initialized = true;
255     }
256 
257     /**
258      * Imports the parameters from <code>params</code> and decodes them 
259      * according to the specified decoding scheme.
260      * If <code>format</code> is null, the
261      * primary decoding format for parameters is used. The primary decoding
262      * format is ASN.1, if an ASN.1 specification for these parameters
263      * exists.
264      *
265      * @param params the encoded parameters.
266      *
267      * @param format the name of the decoding scheme.
268      *
269      * @exception IOException on decoding errors, or if this parameter object
270      * has already been initialized.
271      */
272     public final void init(byte[] params, String   format) throws IOException {
273     if (this.initialized)
274         throw new IOException("already initialized");
275     paramSpi.engineInit(params, format);
276     this.initialized = true;
277     }
278 
279     /**
280      * Returns a (transparent) specification of this parameter object.
281      * <code>paramSpec</code> identifies the specification class in which 
282      * the parameters should be returned. It could, for example, be
283      * <code>DSAParameterSpec.class</code>, to indicate that the
284      * parameters should be returned in an instance of the 
285      * <code>DSAParameterSpec</code> class.
286      *
287      * @param paramSpec the specification class in which 
288      * the parameters should be returned.
289      *
290      * @return the parameter specification.
291      *
292      * @exception InvalidParameterSpecException if the requested parameter
293      * specification is inappropriate for this parameter object, or if this
294      * parameter object has not been initialized.
295      */
296     public final <T extends AlgorithmParameterSpec  >
297     T getParameterSpec(Class  <T> paramSpec)
298     throws InvalidParameterSpecException  
299     {
300     if (this.initialized == false) {
301         throw new InvalidParameterSpecException  ("not initialized");
302     }
303     return paramSpi.engineGetParameterSpec(paramSpec);
304     }
305 
306     /**
307      * Returns the parameters in their primary encoding format.
308      * The primary encoding format for parameters is ASN.1, if an ASN.1
309      * specification for this type of parameters exists.
310      *
311      * @return the parameters encoded using their primary encoding format.
312      *
313      * @exception IOException on encoding errors, or if this parameter object
314      * has not been initialized.
315      */
316     public final byte[] getEncoded() throws IOException
317     {
318     if (this.initialized == false) {
319         throw new IOException("not initialized");
320     }
321     return paramSpi.engineGetEncoded();
322     }
323 
324     /**
325      * Returns the parameters encoded in the specified scheme.
326      * If <code>format</code> is null, the
327      * primary encoding format for parameters is used. The primary encoding
328      * format is ASN.1, if an ASN.1 specification for these parameters
329      * exists.
330      *
331      * @param format the name of the encoding format.
332      *
333      * @return the parameters encoded using the specified encoding scheme.
334      *
335      * @exception IOException on encoding errors, or if this parameter object
336      * has not been initialized.
337      */
338     public final byte[] getEncoded(String   format) throws IOException
339     {
340     if (this.initialized == false) {
341         throw new IOException("not initialized");
342     }
343     return paramSpi.engineGetEncoded(format);
344     }
345 
346     /**
347      * Returns a formatted string describing the parameters.
348      *
349      * @return a formatted string describing the parameters, or null if this
350      * parameter object has not been initialized.
351      */
352     public final String   toString() {
353     if (this.initialized == false) {
354         return null;
355     }
356     return paramSpi.engineToString();
357     }
358 }
359
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags