001 /*
002 * file ProviderFactory.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM
006 *
007 * (c) Copyright IBM Corporation 2004, 2008. All Rights Reserved.
008 * Note to U.S. Government Users Restricted Rights: Use, duplication or
009 * disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
010 */
011 package javax.wvcm;
012
013 import java.lang.reflect.InvocationTargetException;
014 import java.util.Map;
015
016 /**
017 * A factory class for creating instances of a WVCM provider.
018 *
019 * This is a convenience class used to simplify the creation of an instance of a WVCM provider.
020 * A provider is identified by its class name and is runtime loaded.
021 *
022 * @since 1.0
023 */
024 public final class ProviderFactory {
025
026 // no instantiation permitted
027 private ProviderFactory() {}
028
029 /**
030 * Provides callback functions that can be invoked by a provider.
031 */
032 public interface Callback {
033
034 /**
035 * Authentication information for the current user.
036 */
037 public interface Authentication {
038 /**
039 * Returns the login name of the current user.
040 *
041 * @return the login name of the current user.
042 */
043 public String loginName();
044
045 /**
046 * Returns the password of the current user.
047 *
048 * @return the password of the current user.
049 */
050 public String password();
051 }
052
053 /**
054 * Get authentication information for the current user.
055 * <p>
056 * The provider calls Callback.getAuthentication, and the client returns
057 * an object that implements the Authentication interface.
058 * The provider will then call the Authentication interface methods
059 * on that object to obtain authentication information for the current user.
060 *
061 * @param realm an identifier for the authentication realm that is requesting credentials.
062 * A single provider instance can access resources in different authentication realms,
063 * so the user must be provided with the name of the authentication realm in order to
064 * determine what credentials to provide.
065 * @param retryCount the number of times the provider has unsuccessfully
066 * attempted to get authentication for this operation.
067 * This parameter helps the client decide when to provide a more detailed authentication
068 * dialog, or potentially abort the operation rather than making additional attempts
069 * to get credentials from the user.
070 * @return user and password authentication interface.
071 * If null is returned, the user wishes to login anonymously.
072 * @throws WvcmException if the user aborted the authentication request.
073 */
074 public Authentication getAuthentication(String realm, int retryCount) throws WvcmException;
075
076 }
077
078 /**
079 * Create a WVCM provider with the given class name.
080 *
081 * @param providerName the fully-qualified class name of the provider.
082 * @param callback the object containing the getAuthentication
083 * method that the Provider will call whenever it needs
084 * to authenticate the current user.
085 * @return an instance of the Provider whose class name is providerName.
086 * @throws Exception if no class of the given name can be found, loaded, or initialized.
087 */
088 public static Provider createProvider(
089 String providerName,
090 Callback callback)
091 throws Exception {
092 try {
093 return (Provider) Class
094 .forName(providerName)
095 .getConstructor(Callback.class)
096 .newInstance(callback);
097 } catch (InvocationTargetException ex) {
098 Throwable cause = ex.getCause();
099 if (cause instanceof WvcmException)
100 throw (WvcmException)cause;
101 else
102 throw ex;
103 }
104 }
105
106 /**
107 * Get a WVCM provider with the given class name, with specified initializers.
108 *
109 * @param providerName the class name of the provider.
110 * @param callback the object containing the getAuthentication
111 * method that the Provider will call whenever it needs
112 * to authenticate the current user.
113 * @param initArgs a Map containing provider-specific initialization values.
114 * @return an instance of the Provider whose class name is providerName.
115 * @throws Exception if no class of the given name can be found, loaded, or initialized.
116 *
117 * @since 1.1
118 */
119 public static Provider createProvider(
120 String providerName,
121 Callback callback,
122 Map<String, String> initArgs
123 )
124 throws Exception {
125 try {
126 return (Provider) Class
127 .forName(providerName)
128 .getConstructor(Callback.class, Map.class)
129 .newInstance(callback, initArgs);
130 } catch (InvocationTargetException ex) {
131 Throwable cause = ex.getCause();
132 if (cause instanceof WvcmException)
133 throw (WvcmException)cause;
134 else
135 throw ex;
136 }
137 }
138 }