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 }