< prev index next >

src/java.base/share/classes/java/security/AlgorithmParameters.java

Print this page
rev 15967 : [mq]: GetInstance


  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 java.io.*;
  29 import java.security.spec.AlgorithmParameterSpec;
  30 import java.security.spec.InvalidParameterSpecException;

  31 
  32 /**
  33  * This class is used as an opaque representation of cryptographic parameters.
  34  *
  35  * <p>An {@code AlgorithmParameters} object for managing the parameters
  36  * for a particular algorithm can be obtained by
  37  * calling one of the {@code getInstance} factory methods
  38  * (static methods that return instances of a given class).
  39  *
  40  * <p>Once an {@code AlgorithmParameters} object is obtained, it must be
  41  * initialized via a call to {@code init}, using an appropriate parameter
  42  * specification or parameter encoding.
  43  *
  44  * <p>A transparent parameter specification is obtained from an
  45  * {@code AlgorithmParameters} object via a call to
  46  * {@code getParameterSpec}, and a byte encoding of the parameters is
  47  * obtained via a call to {@code getEncoded}.
  48  *
  49  * <p> Every implementation of the Java platform is required to support the
  50  * following standard {@code AlgorithmParameters} algorithms:


 123      * the {@link Security#getProviders() Security.getProviders()} method.
 124      *
 125      * <p> The returned parameter object must be initialized via a call to
 126      * {@code init}, using an appropriate parameter specification or
 127      * parameter encoding.
 128      *
 129      * @implNote
 130      * The JDK Reference Implementation additionally uses the
 131      * {@code jdk.security.provider.preferred}
 132      * {@link Security#getProperty(String) Security} property to determine
 133      * the preferred provider order for the specified algorithm. This
 134      * may be different than the order of providers returned by
 135      * {@link Security#getProviders() Security.getProviders()}.
 136      *
 137      * @param algorithm the name of the algorithm requested.
 138      * See the AlgorithmParameters section in the <a href=
 139      * "{@docRoot}/../technotes/guides/security/StandardNames.html#AlgorithmParameters">
 140      * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
 141      * for information about standard algorithm names.
 142      *
 143      * @return the new parameter object.
 144      *
 145      * @exception NoSuchAlgorithmException if no Provider supports an
 146      *          AlgorithmParametersSpi implementation for the
 147      *          specified algorithm.


 148      *
 149      * @see Provider
 150      */
 151     public static AlgorithmParameters getInstance(String algorithm)
 152     throws NoSuchAlgorithmException {

 153         try {
 154             Object[] objs = Security.getImpl(algorithm, "AlgorithmParameters",
 155                                              (String)null);
 156             return new AlgorithmParameters((AlgorithmParametersSpi)objs[0],
 157                                            (Provider)objs[1],
 158                                            algorithm);
 159         } catch(NoSuchProviderException e) {
 160             throw new NoSuchAlgorithmException(algorithm + " not found");
 161         }
 162     }
 163 
 164     /**
 165      * Returns a parameter object for the specified algorithm.
 166      *
 167      * <p> A new AlgorithmParameters object encapsulating the
 168      * AlgorithmParametersSpi implementation from the specified provider
 169      * is returned.  The specified provider must be registered
 170      * in the security provider list.
 171      *
 172      * <p> Note that the list of registered providers may be retrieved via
 173      * the {@link Security#getProviders() Security.getProviders()} method.
 174      *
 175      * <p>The returned parameter object must be initialized via a call to
 176      * {@code init}, using an appropriate parameter specification or
 177      * parameter encoding.
 178      *
 179      * @param algorithm the name of the algorithm requested.
 180      * See the AlgorithmParameters section in the <a href=
 181      * "{@docRoot}/../technotes/guides/security/StandardNames.html#AlgorithmParameters">
 182      * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
 183      * for information about standard algorithm names.
 184      *
 185      * @param provider the name of the provider.
 186      *
 187      * @return the new parameter object.



 188      *
 189      * @exception NoSuchAlgorithmException if an AlgorithmParametersSpi
 190      *          implementation for the specified algorithm is not
 191      *          available from the specified provider.
 192      *
 193      * @exception NoSuchProviderException if the specified provider is not
 194      *          registered in the security provider list.
 195      *
 196      * @exception IllegalArgumentException if the provider name is null
 197      *          or empty.
 198      *
 199      * @see Provider
 200      */
 201     public static AlgorithmParameters getInstance(String algorithm,
 202                                                   String provider)
 203         throws NoSuchAlgorithmException, NoSuchProviderException
 204     {

 205         if (provider == null || provider.length() == 0)
 206             throw new IllegalArgumentException("missing provider");
 207         Object[] objs = Security.getImpl(algorithm, "AlgorithmParameters",
 208                                          provider);
 209         return new AlgorithmParameters((AlgorithmParametersSpi)objs[0],
 210                                        (Provider)objs[1],
 211                                        algorithm);
 212     }
 213 
 214     /**
 215      * Returns a parameter object for the specified algorithm.
 216      *
 217      * <p> A new AlgorithmParameters object encapsulating the
 218      * AlgorithmParametersSpi implementation from the specified Provider
 219      * object is returned.  Note that the specified Provider object
 220      * does not have to be registered in the provider list.
 221      *
 222      * <p>The returned parameter object must be initialized via a call to
 223      * {@code init}, using an appropriate parameter specification or
 224      * parameter encoding.
 225      *
 226      * @param algorithm the name of the algorithm requested.
 227      * See the AlgorithmParameters section in the <a href=
 228      * "{@docRoot}/../technotes/guides/security/StandardNames.html#AlgorithmParameters">
 229      * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
 230      * for information about standard algorithm names.
 231      *
 232      * @param provider the name of the provider.
 233      *
 234      * @return the new parameter object.


 235      *
 236      * @exception NoSuchAlgorithmException if an AlgorithmParameterGeneratorSpi

 237      *          implementation for the specified algorithm is not available
 238      *          from the specified Provider object.
 239      *
 240      * @exception IllegalArgumentException if the provider is null.
 241      *
 242      * @see Provider
 243      *
 244      * @since 1.4
 245      */
 246     public static AlgorithmParameters getInstance(String algorithm,
 247                                                   Provider provider)
 248         throws NoSuchAlgorithmException
 249     {

 250         if (provider == null)
 251             throw new IllegalArgumentException("missing provider");
 252         Object[] objs = Security.getImpl(algorithm, "AlgorithmParameters",
 253                                          provider);
 254         return new AlgorithmParameters((AlgorithmParametersSpi)objs[0],
 255                                        (Provider)objs[1],
 256                                        algorithm);
 257     }
 258 
 259     /**
 260      * Returns the provider of this parameter object.
 261      *
 262      * @return the provider of this parameter object
 263      */
 264     public final Provider getProvider() {
 265         return this.provider;
 266     }
 267 
 268     /**
 269      * Initializes this parameter object using the parameters




  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 java.io.*;
  29 import java.security.spec.AlgorithmParameterSpec;
  30 import java.security.spec.InvalidParameterSpecException;
  31 import java.util.Objects;
  32 
  33 /**
  34  * This class is used as an opaque representation of cryptographic parameters.
  35  *
  36  * <p>An {@code AlgorithmParameters} object for managing the parameters
  37  * for a particular algorithm can be obtained by
  38  * calling one of the {@code getInstance} factory methods
  39  * (static methods that return instances of a given class).
  40  *
  41  * <p>Once an {@code AlgorithmParameters} object is obtained, it must be
  42  * initialized via a call to {@code init}, using an appropriate parameter
  43  * specification or parameter encoding.
  44  *
  45  * <p>A transparent parameter specification is obtained from an
  46  * {@code AlgorithmParameters} object via a call to
  47  * {@code getParameterSpec}, and a byte encoding of the parameters is
  48  * obtained via a call to {@code getEncoded}.
  49  *
  50  * <p> Every implementation of the Java platform is required to support the
  51  * following standard {@code AlgorithmParameters} algorithms:


 124      * the {@link Security#getProviders() Security.getProviders()} method.
 125      *
 126      * <p> The returned parameter object must be initialized via a call to
 127      * {@code init}, using an appropriate parameter specification or
 128      * parameter encoding.
 129      *
 130      * @implNote
 131      * The JDK Reference Implementation additionally uses the
 132      * {@code jdk.security.provider.preferred}
 133      * {@link Security#getProperty(String) Security} property to determine
 134      * the preferred provider order for the specified algorithm. This
 135      * may be different than the order of providers returned by
 136      * {@link Security#getProviders() Security.getProviders()}.
 137      *
 138      * @param algorithm the name of the algorithm requested.
 139      * See the AlgorithmParameters section in the <a href=
 140      * "{@docRoot}/../technotes/guides/security/StandardNames.html#AlgorithmParameters">
 141      * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
 142      * for information about standard algorithm names.
 143      *
 144      * @return the new parameter object
 145      *
 146      * @throws NoSuchAlgorithmException if no {@code Provider} supports an
 147      *         {@code AlgorithmParametersSpi} implementation for the
 148      *         specified algorithm
 149      *
 150      * @throws NullPointerException if {@code algorithm} is {@code null}
 151      *
 152      * @see Provider
 153      */
 154     public static AlgorithmParameters getInstance(String algorithm)
 155     throws NoSuchAlgorithmException {
 156         Objects.requireNonNull(algorithm, "null algorithm name");
 157         try {
 158             Object[] objs = Security.getImpl(algorithm, "AlgorithmParameters",
 159                                              (String)null);
 160             return new AlgorithmParameters((AlgorithmParametersSpi)objs[0],
 161                                            (Provider)objs[1],
 162                                            algorithm);
 163         } catch(NoSuchProviderException e) {
 164             throw new NoSuchAlgorithmException(algorithm + " not found");
 165         }
 166     }
 167 
 168     /**
 169      * Returns a parameter object for the specified algorithm.
 170      *
 171      * <p> A new AlgorithmParameters object encapsulating the
 172      * AlgorithmParametersSpi implementation from the specified provider
 173      * is returned.  The specified provider must be registered
 174      * in the security provider list.
 175      *
 176      * <p> Note that the list of registered providers may be retrieved via
 177      * the {@link Security#getProviders() Security.getProviders()} method.
 178      *
 179      * <p>The returned parameter object must be initialized via a call to
 180      * {@code init}, using an appropriate parameter specification or
 181      * parameter encoding.
 182      *
 183      * @param algorithm the name of the algorithm requested.
 184      * See the AlgorithmParameters section in the <a href=
 185      * "{@docRoot}/../technotes/guides/security/StandardNames.html#AlgorithmParameters">
 186      * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
 187      * for information about standard algorithm names.
 188      *
 189      * @param provider the name of the provider.
 190      *
 191      * @return the new parameter object
 192      *
 193      * @throws IllegalArgumentException if the provider name is {@code null}
 194      *         or empty
 195      *
 196      * @throws NoSuchAlgorithmException if an {@code AlgorithmParametersSpi}
 197      *         implementation for the specified algorithm is not
 198      *         available from the specified provider
 199      *
 200      * @throws NoSuchProviderException if the specified provider is not
 201      *         registered in the security provider list
 202      *
 203      * @throws NullPointerException if {@code algorithm} is {@code null}

 204      *
 205      * @see Provider
 206      */
 207     public static AlgorithmParameters getInstance(String algorithm,
 208                                                   String provider)
 209         throws NoSuchAlgorithmException, NoSuchProviderException
 210     {
 211         Objects.requireNonNull(algorithm, "null algorithm name");
 212         if (provider == null || provider.length() == 0)
 213             throw new IllegalArgumentException("missing provider");
 214         Object[] objs = Security.getImpl(algorithm, "AlgorithmParameters",
 215                                          provider);
 216         return new AlgorithmParameters((AlgorithmParametersSpi)objs[0],
 217                                        (Provider)objs[1],
 218                                        algorithm);
 219     }
 220 
 221     /**
 222      * Returns a parameter object for the specified algorithm.
 223      *
 224      * <p> A new AlgorithmParameters object encapsulating the
 225      * AlgorithmParametersSpi implementation from the specified Provider
 226      * object is returned.  Note that the specified Provider object
 227      * does not have to be registered in the provider list.
 228      *
 229      * <p>The returned parameter object must be initialized via a call to
 230      * {@code init}, using an appropriate parameter specification or
 231      * parameter encoding.
 232      *
 233      * @param algorithm the name of the algorithm requested.
 234      * See the AlgorithmParameters section in the <a href=
 235      * "{@docRoot}/../technotes/guides/security/StandardNames.html#AlgorithmParameters">
 236      * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
 237      * for information about standard algorithm names.
 238      *
 239      * @param provider the name of the provider.
 240      *
 241      * @return the new parameter object
 242      *
 243      * @throws IllegalArgumentException if the provider is {@code null}
 244      *
 245      * @throws NoSuchAlgorithmException if an
 246      *         {@code AlgorithmParameterGeneratorSpi}
 247      *         implementation for the specified algorithm is not available
 248      *         from the specified {@code Provider} object
 249      *
 250      * @throws NullPointerException if {@code algorithm} is {@code null}
 251      *
 252      * @see Provider
 253      *
 254      * @since 1.4
 255      */
 256     public static AlgorithmParameters getInstance(String algorithm,
 257                                                   Provider provider)
 258         throws NoSuchAlgorithmException
 259     {
 260         Objects.requireNonNull(algorithm, "null algorithm name");
 261         if (provider == null)
 262             throw new IllegalArgumentException("missing provider");
 263         Object[] objs = Security.getImpl(algorithm, "AlgorithmParameters",
 264                                          provider);
 265         return new AlgorithmParameters((AlgorithmParametersSpi)objs[0],
 266                                        (Provider)objs[1],
 267                                        algorithm);
 268     }
 269 
 270     /**
 271      * Returns the provider of this parameter object.
 272      *
 273      * @return the provider of this parameter object
 274      */
 275     public final Provider getProvider() {
 276         return this.provider;
 277     }
 278 
 279     /**
 280      * Initializes this parameter object using the parameters


< prev index next >