com.hyperion.css
Class CSSSystem

java.lang.Object
  com.hyperion.css.CSSSystem

public class CSSSystem
extends java.lang.Object

This is a class is responsible to initialize the security client system in one of the following modes depending on the value of the flag stored in EPM Registry:

Fusion/JPS

EPM

The value FUSIONAPPS in the EPM Registry stored under EPM_SYSTEM_PRODUCT@mode will direct the security system client to initialize in Fusion/JPS mode. In this mode the security client interacts with the underlying JPS API's all authentication, authorization and other search requests.

Note that in the JPS mode, the security client required the configuration files and binaries required by JPS. Only a subset of the public API are supported in this mode. Any unsupported API's will throw CSSMethodNotSupportedException. This mode does not support or require EPM Shared Services and Native Directory.

When the EPM registry flag is set to any other value or not available the security system will initialize in EPM (Normal) mode with full support for all API's. All User Directories will including Native, LDAP, MSAD, SAP and DB will be supported in this mode. This mode requires EPM Shared Services to be running.

The EPM mode can be initialized thru the Security configuration stored in the registry or the by specifying the configuration url.

This is a Singleton class and is guaranteed to return the same instance in any given JVM once initialized.

This Security System class provides handle to the following public interfaces:

CSSAPIIF

CSSDirectoryManagementIF (available only in EPM mode)

CSSUserProvisioningIF

Sample use of the application:

 <code>
    Map context = new HashMap(5);
    context.put(CSSAPIIF.LOCALE, new Locale("en", "US"));     
    String logPath = "C:/Hyperion/logs/";
    
    CSSSystem instance = CSSSystem.getInstance(context, logPath);
    CSSAPIIF css = instance.getCSSAPI();
 
    // Host information (IP address/Host Name) is required for Auditing.
    context.put(CSSAPIIF.HOST_INFO, "host1.hyperion.com");
 
    try
    {
        context.put(CSSAPIIF.LOGIN_NAME, "user");
        context.put(CSSAPIIF.PASSWORD, "password");
 
      CSSUserIF user = css.authenticate(context);
    }
    catch (CSSTokenNotAvailableException tNAE)
    {
       // log this
       // check message and error code for more info
       // try again
    }
    catch (CSSAuthenticationException aE)
    {
       // Unable to authenticate
       // check credentials
       // check message and error code for more info
       // log this
    }
    catch (CSSIllegalArgumentException iAE)
    {
       // check arguments and correct them according to the contract
       // check message and error code for more info
       // try again
    }
    catch (CSSNoProviderException nPE)
    {
       // CSS was unable to launch a provider
       // that was requested in the provider entry in the context
       // check message and error code for more info
       // check and try again
       // log this
    }
    catch (CSSInvalidIdentityException iIE)
    {
       // Unable to use the identity passed in the token
       // log this
    }
    catch (CSSTokenNotAcceptedException tNAcceptedE)
    {
       // the token passed in is not valid
       // log this
    }
    catch (CSSException e)
    {
       // Any other abnormality
       // check message and error code for more info
       // log this
    }
 </code>
 

Since:

CSSv1.0

Field Summary

static int	EPM_MODE Constant specifying EPM mode of CSS initialization.
static int	FUSION_MODE Constant specifying Fusion mode of CSS initialization.
static java.lang.String	NO_CACHE Constant specifying that NO Cache should be initialized during CSS initialization.

Method Summary

static com.hyperion.css.common.configuration.CSSConfigurationManager	getConfigurationManager() Return the Configuration Manager.
CSSAPIIF	getCSSAPI() Returns the entry point to the security platform API.
static CSSSystem	getCSSSystem() Returns an instance of CSSSystem if the the system has been already initialized, returns null otherwise.
static CSSSystem	getInstance() Deprecated.
static CSSSystem	getInstance(java.util.Map context, java.lang.String logPath) Returns an initialized singleton instance of CSSSystem using the configuration from EPM Registry.
static CSSSystem	getInstance(java.util.Map context, java.net.URL configURL, java.lang.String logPath) Deprecated. (non-Javadoc) This is an EPM mode only API. Returns an initialized singleton instance of CSSSystem using the specified configURL. Note that if the CSSSystem was already initialized using configuration from registry, the system will not initialize again, but the same instance would be returned. A warning would be logged. If Native directory is not reachable, the initialization logic will try to reconnect to it for a few attempts. If Native directory is not reachable even after retry attempts, this method will fail with exception. The context can specify the following: locale NO_CACHE - Note that setting this option will only defer the cache building from initialize time to when required. The directory location of where the client log file should be created is required, In case of invalid log location, the log will be created in the JVM temp folder.
static com.hyperion.css.spi.CSSManager	getManager() This is an EPM mode only API.
static int	getMode() Gets the working mode of this CSS system.
java.lang.String	getSAPTicket(java.util.Map context, java.lang.String cSSToken) This is an EPM mode only API
static java.lang.String	restoreToken(java.util.Map context, java.lang.String token) Deprecated. - use restoreToken(Map, String, String)
java.lang.String	restoreToken(java.util.Map context, java.lang.String token, java.lang.String trustedServiceKey) Validates the token and renews it for a time period specified in the SSO token timeout configuration property.
void	shutdown() Shuts down the security platform.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

EPM_MODE

public static final int EPM_MODE

Constant specifying EPM mode of CSS initialization.

The value is 0.

See Also:

Constant Field Values

FUSION_MODE

public static final int FUSION_MODE

Constant specifying Fusion mode of CSS initialization.

The value is 1.

See Also:

Constant Field Values

NO_CACHE

public static java.lang.String NO_CACHE

Constant specifying that NO Cache should be initialized during CSS initialization. The value of this constant is "noCache".

Method Detail

getCSSAPI

public CSSAPIIF getCSSAPI()

Returns the entry point to the security platform API.

Returns:

an implementation of CSSAPIIF - CSSAPIImpl or FusionImpl

getCSSSystem

public static CSSSystem getCSSSystem()

Returns an instance of CSSSystem if the the system has been already initialized, returns null otherwise.

getConfigurationManager

public static com.hyperion.css.common.configuration.CSSConfigurationManager getConfigurationManager()
                                                                                             throws CSSException

Return the Configuration Manager.

This API will be supported only in EPM mode.

Returns:

CSSConfigurationManager

Throws:

CSSMethodNotSupportedException - - if this method is invoked in Fusion mode.

CSSException - - if there was any other abnormality

getInstance

public static CSSSystem getInstance(java.util.Map context,
                                    java.lang.String logPath)
                             throws CSSException

Returns an initialized singleton instance of CSSSystem using the configuration from EPM Registry. Note that the initialization requires the Registry api's to be present in classpath and Registry service (database) to be up and running. In case the Registry is not reachable, the initialization will fail with an exception.

In Fusion/JPS mode, the initialization will use JPS configuration file to initialize JPS and return the system instance. This is the recommended API to initialize Security system client in Fusion/JPS mode.

In EPM mode, if Native directory is not reachable, the initialization logic will try to reconnect to it for a few attempts. If Native directory is not reachable even after retry attempts, this method will fail with exception.

The context can specify the following (EPM mode only):

1. locale
2. NO_CACHE - Note that setting this option will only defer the cache building from initialize time to when required.

The directory location of where the client log file should be created is required, In case of invalid log location, the log will be created in the JVM temp folder.

Parameters:

context - Map structure holding locale information.

logPath - - directory location of where the client log should be created.

Returns:

CSSSystem

Throws:

CSSException

getInstance

public static CSSSystem getInstance()

Deprecated.

Use getInstance(Map, String) instead.

getInstance

public static CSSSystem getInstance(java.util.Map context,
                                    java.net.URL configURL,
                                    java.lang.String logPath)
                             throws CSSException

Deprecated. (non-Javadoc) This is an EPM mode only API.

Returns an initialized singleton instance of CSSSystem using the specified configURL. Note that if the CSSSystem was already initialized using configuration from registry, the system will not initialize again, but the same instance would be returned. A warning would be logged.

If Native directory is not reachable, the initialization logic will try to reconnect to it for a few attempts. If Native directory is not reachable even after retry attempts, this method will fail with exception.

The context can specify the following:

1. locale
2. NO_CACHE - Note that setting this option will only defer the cache building from initialize time to when required.

The directory location of where the client log file should be created is required, In case of invalid log location, the log will be created in the JVM temp folder.

Parameters:

context - Map structure holding locale information.

configURL - - valid url pointing to CSS configuration file

logPath - - directory location of where the client log should be created.

Returns:

- instance of CSS System.

Throws:

CSSException - - in case of any failures.

getMode

public static int getMode()

Gets the working mode of this CSS system.

CSS can initialize in EPM mode or Fusion mode. This method finds the current mode and returns it.

Returns:

integer having one of the values CSSSystem.EPM_MODE or CSSSystem.FUSION_MODE

getSAPTicket

public java.lang.String getSAPTicket(java.util.Map context,
                                     java.lang.String cSSToken)
                              throws CSSException

This is an EPM mode only API

Retrieves the SAP Login Ticket if the CSS token can retrieve it.

The context can specify the following:

1. locale

Please make sure that the CSS system is initialized before invoking this method.

These properties are discussed in the field description at CSSAPIIF. Please note that if the locale is not specified, the default locale set for the system is used.

Parameters:

context - - Map structure holding key-value information about locale.

cSSToken - - the CSS token string

Returns:

- the SAP Login Ticket otherwise null

Throws:

CSSException - - Any abnormality

getManager

public static com.hyperion.css.spi.CSSManager getManager()
                                                  throws CSSException

This is an EPM mode only API.

Returns an instance of CSS Manager if CSS is already initialized, returns null otherwise.

Throws:

CSSMethodNotSupportedException - - if this method is invoked in Fusion mode.

CSSException - - if there was any other abnormality

shutdown

public void shutdown()
              throws CSSException

Shuts down the security platform. Method releases resources used by the CSS system, for e.g., business cache threads.

Calling this before JVM shutdown will avoid the need for a forcible JVM exit. Calling shutdown and initialize after that in the same JVM is not supported.

Usage:

 // get CSSSystem instance
 CSSSystem cssSystem = CSSystem.getInstance(context, "C:\work\Hyperion");
 CSSAPIIF cssAPI = cssSystem.getCSSAPI();
 
 // perform CSS operation
 cssAPI.authenticate(context,"ABCUser","ABCPassword");
 
 // shutdown
 cssSystem.shutdown();
 

Throws:

CSSException - - if there is any abnormality in releasing resources.

Since:

11.1.1.1.00

restoreToken

public static java.lang.String restoreToken(java.util.Map context,
                                            java.lang.String token)
                                     throws CSSException

Deprecated. - use restoreToken(Map, String, String)

Creates a new token based on the passed-in token. Use when the existing token is going to expire.

Parameters:

token - - existing token.

Returns:

string - new token similar to the existing one, but with the token timeout extended.

Throws:

CSSException - - if there is any problem parsing the existing token or creating the new one.

restoreToken

public java.lang.String restoreToken(java.util.Map context,
                                     java.lang.String token,
                                     java.lang.String trustedServiceKey)
                              throws CSSException

Validates the token and renews it for a time period specified in the SSO token timeout configuration property. The original token credentials will be retained in the restored token.

Parameters:

token - - original token which has reached its expiration time and needs to be restored.

trustedServiceKey - - value of the security trusted key.

Throws:

CSSException - - if there is any problem parsing the existing token or creating the new one; if there is any problem retrieving the trusted key

Since:

v11.1.2.1