amwebarsentitlementservice
Interface AMWebARSEntitlementService

All Known Implementing Classes:
AMWebARSEntitlementServiceImplementation

public interface AMWebARSEntitlementService

The AMWebARSEntitlementService is the front interface of the project which manages the communication with Access Manager. It consists of three methods: initialize(), getEntitlement() and shutdown(). The ErrorCodes that these methods return are described in the interface ErrorCodes. Before the AMWebARSEntitlementService can be used, the initialize() method has to be called. This method loads all data tables and performs the initialisation of all data structures that will be used during all requests. If you call getEntitlement() before the initialisation finished successfully the getEntitlement() method will return an error code. The getEntitlement() method retrieves a set of containers from different providers. It generates one Session per request and several AMWebARSClients. For one subject there can only be one Session be active at one time. Therefore several requests for the same UUID are performed sequentially. The shutdown() method cleans up all data structures and ensures that all log entries ere written to disk. After this method is called, the AMWebARSEntitlementService isn't considered initialized anymore. You have to reinitialize it to use it again.

Error Codes

The returned Map will contain one or more (error code/description) pairs in the "azn_ent_svc_err_error_list" value if something went wrong. The value corresponding to the ErrorCodes.AZN_ENT_SVC_ERR_ERROR_CODE_STR key contains the hex error code with the least hex number. That one is considered to be worst. Example: Let's consider this Map.
 {
   azn_ent_svc_err_error_list=
      [1f: One or more container_type_ids requested aren't valid: 
          [test_failure, test_failure2]], 
   azn_ent_svc_err_error_code=[1f],
   http://www.rigenbach.de/:file_reader__test_container_credit_line=
       [
            1000 USD
	      ], 
   http://www.rigenbach.de/:file_reader__test_container_adress_line=
 	     [
            Arlington Road 15, LA, California, USA
        ]
 }
 
The first entry denotes the error list. It contains a minor error code: some container_type_ids are missing. The following entry is the over all error code. The next two keys refer to two containers with an entitlements for the subject. The key of this pair is a container_type_id.

See Also:
AMWebARSEntitlementServiceImplementation

Field Summary
static java.lang.String UNAUTHENTICATED_UUID
          This String denotes the UUID "unauthenticated", which can't be handled by the AMWebARSEntitlementService.
 
Method Summary
 java.util.Map getEntitlement(java.util.Map credential, java.lang.String svc_id, java.util.Map app_context)
          Retrieves several dynADI containers for a given subject from different providers.
 java.util.Map initialize(java.lang.String[] argv, java.util.Map svc_init)
          Initializes the AMWebARSEntitlementService.
 java.util.Map shutdown(java.lang.String[] argv, java.util.Map svc_init)
          Shutdown the AMWebARSEntitlementService.
 

Field Detail

UNAUTHENTICATED_UUID

public static final java.lang.String UNAUTHENTICATED_UUID
This String denotes the UUID "unauthenticated", which can't be handled by the AMWebARSEntitlementService.
Method Detail

getEntitlement

public java.util.Map getEntitlement(java.util.Map credential,
                                    java.lang.String svc_id,
                                    java.util.Map app_context)
Retrieves several dynADI containers for a given subject from different providers. The method generates a new Session per request and several AMWebARSClients. For one subject there can only be one Session be active at one time. Therefore several requests for the same UUID are performed sequentially. The method adds the AMWebARSContainerDescriptors requested by the AccessManager to the Session and calls its run() method.
Parameters:
credential - This Map contains information of the credential of the subject of the request. The cred_principal_uuid has to be set and musn't be 'unauthenticated'. The param cred_user_info contains data about the user needed to identify him during a protocol run. The keys that are valid for the Map are described in the interface CredentialKeys.
svc_id - String Service ID of this Service. Can be null.
app_context - This Map contains the data about the request. The key "azn_amwebars_target_url" denotes the URL that the user requested. The key "azn_perminfo_rules_adi_request" contains a List of the requested container_type_ids. Keep in mind that the container_type_ids have to be conform to the XML element name format. The valid keys for this Map are described in the interface AppContextKeys.
Returns:
Map that contains the following information:
  • For each container successfully retrieved, the String format of its XML description stored under its container_type_id.
  • If the AMWebARSEntitlementService can't retrieve all containers, an additional key-value-pair is added to the Map: The String format of a redirect URL under key "azn_perminfo_amwebars_redirect_url".
  • If an error occured the key "azn_ent_svc_err_error_code" refers to the over all error code as hex value. Please not that all error codes that might occur are described in the interface ErrorCodes.
  • If an error occured the key "azn_ent_svc_err_error_list" refers to an List of all errors the happeded during the method run. This List contains a pair of (error code, description) for each error.
If the method returned without error and no container was retrieved, it returns an empty Map.
See Also:
ErrorCodes, AppContextKeys, CredentialKeys, AMWebARSEntitlementServiceImplementation.getEntitlement(Map, String, Map)

initialize

public java.util.Map initialize(java.lang.String[] argv,
                                java.util.Map svc_init)
Initializes the AMWebARSEntitlementService. Before the AMWebARSEntitlementService can be used, the initialize method has to be called. This method loads all data tables and performs the initialisation of all data structures that will be used during all requests. If you call getEntitlement() before the initialisation finished successfully the getEntitlement() method will return an error code. The following tasks have to be done:
Parameters:
argv - String[] as described in the Authentication C API description
svc_init - as described in the Authentication C API description. There are no special attributes yet.
Returns:
Map status description. It contains:
  • If an error occured the key "azn_ent_svc_err_error_code" refers to the over all error code as hex value. Please not that all error codes that might occur are described in the interface ErrorCodes.
  • If an error occured the key "azn_ent_svc_err_error_list" refers to an List of all errors the happeded during the method run. This List contains a pair of (error code, description) for each error.
If the method returned without error, it returns an empty Map.
See Also:
shutdown(String[], Map), AMWebARSEntitlementServiceImplementation.initialize(String[], Map)

shutdown

public java.util.Map shutdown(java.lang.String[] argv,
                              java.util.Map svc_init)
Shutdown the AMWebARSEntitlementService. This method cleans up all data structures and ensures that all log entries were written to disk. After this method is called, the AMWebARSEntitlementService isn't considered initialized anymore. You have to reinitialize it to use it again.
Parameters:
argv - String[] as described in the Authentication C API description
svc_init - as described in the Authentication C API description. There are no special attributes yet.
Returns:
Map status description. It contains:
  • If an error occured the key "azn_ent_svc_err_error_code" refers to the over all error code as hex value. Please not that all error codes that might occur are described in the interface ErrorCodes.
  • If an error occured the key "azn_ent_svc_err_error_list" refers to an List of all errors the happeded during the method run. This List contains a pair of (error code, description) for each error.
If the method returned without error, it returns an empty Map.
See Also:
initialize(String[], Map), AMWebARSEntitlementServiceImplementation.shutdown(String[], Map)