### *** This class provides Binary Compatibility only, not Source Compatibility ***

Package com.sas.services.session

# Class SessionServiceInitObject

java.lang.Object
com.sas.services.AbstractServiceComponentConfig
com.sas.services.session.SessionServiceInitObject

All Implemented Interfaces:
  `ServiceComponentConfigInterface`, `Cloneable`

@SASScope("ALL") @BinaryCompatibilityOnly public final class SessionServiceInitObject extends AbstractServiceComponentConfig
Session Service configuration which may specify the default user context to associate with the root session context and optionally a session context timeout.

## XML Schema

The Session Service is described by an XML schema.

## Configuration Merging

This service provides the capability to update its configuration by merging another configuration, so long as no conflicts exist. The following table documents what can be merged and constraints which must be satisfied in order for a merge to be accepted.

Configuration Merging
Item | Constraints
--- | ---
user context name | This value can be updated if the current value is undefined.
timeout | This value can be updated if the current value is undefined.

## Foundation Services Manager plug-in

The Foundation Services Manager plug-in to the SAS Management Console provides the capability to save a Session Service configuration to a UTF-8 encoded XML file. The plug-in also provides the capability to merge a Session Service configuration from a file.

## Sample Configuration

A configuration file, created by the Foundation Services Manager plug-in, is provided as a sample.

Since:
  1.0

- ## Field Summary

  ### Fields inherited from class com.sas.services.AbstractServiceComponentConfig

  `ENCODING, LOOKUPKEY_PROPERTYNAME_VIEWCLASS, PROPERTY_NAME_INIT_DATA, PROPERTY_NAME_INITIALIZATIONDATA, PROPERTYROLE_APPCONFIG, PROPERTYROLE_INITIALIZATION, XML_ELEMENT_ATTRIBUTE_VERSION`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `SessionServiceInitObject()`
  Constructs a default instance of a session service configuration.
  `SessionServiceInitObject(InputStream configInputStream)`
  Constructs an instance which will be initialized with the service configuration read from the specified input stream.
  `SessionServiceInitObject(String defaultUser)`
  Constructs an instance of a session service configuration using the specified user context name.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Consumer`
  `addConsumer(Consumer consumer, boolean isConsumer)`
  Adds the consumer to the usage model specifying its use of defined service configuration resources.
  `DocumentFragment`
  `appendDOM(Document document)`
  Appends elements to the specified XML document representing the Session Service component's configuration.
  `protected DocumentFragment`
  `appendDOM(Document document, AbstractServiceComponentConfig serviceConfig)`
  Constructs a document object model representing the configuration data for a foundation user service.
  `static DocumentFragment`
  `appendDOM(Document document, SessionServiceInitObject serviceConfig)`
  Appends elements to the specified XML document representing the Session Service component's configuration.
  `static Long`
  `convertMinutesToMsec(Long minutes)`
  Converts from minutes to msec.
  `protected AbstractServiceComponentConfig`
  `createConfiguration(Document document)`
  Creates a service configuration initialized with the specified XML document.
  `boolean`
  `equals(Object o)`
  Determines whether or not the specified object is equivalent to this object.
  `protected AbstractServiceComponentConfig`
  `getConfig(Document serviceConfigDocument)`
  Gets an object representing the service's configuration data obtained from the specified XML document.
  `String`
  `getConfirmDeleteUnusedResourceMsg(ConsumedResourceInterface consumedResource)`
  Gets a localized message which can be used in a confirmation dialog that is presented to notify the user the specified unused resource will be deleted.
  `String`
  `getConfirmDeleteUnusedResourcesMsg()`
  Gets a localized message which can be used in a confirmation dialog that is presented to notify the user that unused resources will be deleted.
  `protected String`
  `getServiceFactoryClassName()`
  Gets the session service factory's fully-qualified Java class name.
  `Long`
  `getSessionContextTimeout()`
  Get session context timeout value in units of msec.
  `Long`
  `getSessionContextTimeoutMinutes()`
  Get session context timeout value in units of minutes.
  `String`
  `getUserContextName()`
  Get default platform user context name.
  `int`
  `hashCode()`
  Gets the hash code.
  `protected void`
  `mergeConfiguration(AbstractServiceComponentConfig currentConfig, AbstractServiceComponentConfig newConfig)`
  Merges the new user service configuration into the current configuration.
  `protected void`
  `mergeConfiguration(AbstractServiceComponentConfig currentConfig, AbstractServiceComponentConfig newConfig, MergePolicy mergePolicy)`
  Merges the new user service configuration into the current configuration.
  `Consumer`
  `removeConsumer(Consumer consumer, boolean isRemoveResourceIfUnused)`
  Removes the consumer from the usage model.
  `void`
  `setIsConsumer(Consumer consumer, boolean isConsumer)`
  Specifies consumer use of all of the the service configuration's resources.
  `void`
  `setSessionContextTimeout(Long sessionContextTimeoutMsec)`
  Sets session context timeout given a value in units of msec.
  `void`
  `setSessionContextTimeoutMinutes(Long sessionContextTimeoutMinutes)`
  Sets session context timeout given a value in units of minutes.
  `void`
  `setUserContextName(String defaultUserContextName)`
  Sets the default user context name.
  `protected void`
  `validateServiceConfigurationCustom(Document document)`
  Determines whether or not the service configuration is valid for this service component.

  ### Methods inherited from class com.sas.services.AbstractServiceComponentConfig

  `addResource, addResourceAdapter, clone, convertDocumentToString, createDocument, getBaseConfigName, getConfigName, getConfigName, getConsumedResourceAdapter, getConsumersForResource, getConsumerUsage, getDefaultMergePolicy, getDocument, getOutputFormatProperties, getPrimeNumber, getResourcesWhichUseResource, getServiceClassIdentifiers, getServiceComponentConfigTextStore, getServiceComponentConfiguration, getServiceComponentConfigurationFromTextStore, getServiceConfigProperty, getTextStoreServiceConfig, getUnusedResources, getUsageVersion, getUsageVersionCurrent, getUsageVersionOldest, isBaseConfig, isBaseConfiguration, isConfigurationUpdateable, isOKToRemoveResource, mergeConfig, mergeConfigFromDocument, mergeConfigFromFile, mergeConfiguration, mergeConfiguration, parseConsumerUsage, readServiceConfigFromFile, removeConsumedResource, removeConsumer, removeResource, removeResourceAdapter, setConfig, setConfigName, setConfigName, setConsumerUsage, setTextStoreServiceConfig, setUsageVersion, setUsageVersionCompatibility, toDocument, toXMLString, validateServiceComponent, validateServiceConfiguration, writeServiceConfigToFile, writeServiceConfigToFile`

  ### Methods inherited from class java.lang.Object

  `finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### SessionServiceInitObject

    public SessionServiceInitObject()
    Constructs a default instance of a session service configuration.

  - ### SessionServiceInitObject

    public SessionServiceInitObject(InputStream configInputStream) throws IllegalArgumentException
    Constructs an instance which will be initialized with the service configuration read from the specified input stream.

    The input stream must designate a resource that contains a UTF-8 encoded Logging Service configuration such as one that has been exported by the Foundation Services Manager plug-in to the SAS Management Console.

    Parameters:
      `configInputStream` - An input stream to a UTF-8 encoded XML document used to represent the service component's configuration.
    Throws:
      `IllegalArgumentException` - if an invalid URL is specified.

  - ### SessionServiceInitObject

    public SessionServiceInitObject(String defaultUser)
    Constructs an instance of a session service configuration using the specified user context name.
    Parameters:
      `defaultUser` - The default platform user context name. This identifies the name of the user context to be used by the root session context.

- ## Method Details

  - ### createConfiguration

    protected AbstractServiceComponentConfig createConfiguration(Document document) throws ServiceException
    Creates a service configuration initialized with the specified XML document.
    Overrides:
      `createConfiguration` in class `AbstractServiceComponentConfig`
    Parameters:
      `document` - XML describing the service's configuration.
    Returns:
      Session Service `configuration` initialized from the the XML document.
    Throws:
      `ServiceException` - if unable to create a configuration.

  - ### getConfirmDeleteUnusedResourcesMsg

    public String getConfirmDeleteUnusedResourcesMsg()
    Gets a localized message which can be used in a confirmation dialog that is presented to notify the user that unused resources will be deleted.

    Overrides the default message to say that the session context timeout and user context name will be reset to their default values.

    Overrides:
      `getConfirmDeleteUnusedResourcesMsg` in class `AbstractServiceComponentConfig`
    Returns:
      Localized confirm delete message.

  - ### getConfirmDeleteUnusedResourceMsg

    public String getConfirmDeleteUnusedResourceMsg(ConsumedResourceInterface consumedResource)
    Gets a localized message which can be used in a confirmation dialog that is presented to notify the user the specified unused resource will be deleted.

    Overrides the super-class implementation with a message that says the unused JAAS login configuration name will be reset to its default value.

    Overrides:
      `getConfirmDeleteUnusedResourceMsg` in class `AbstractServiceComponentConfig`
    Parameters:
      `consumedResource` - The consumed resource which is being removed.
    Returns:
      Localized confirm delete message.

  - ### setUserContextName

    public void setUserContextName(String defaultUserContextName)
    Sets the default user context name.
    Parameters:
      `defaultUserContextName` - Default user context name.

  - ### getUserContextName

    public String getUserContextName()
    Get default platform user context name. This identifies the name of user context to be used by the root session context.
    Returns:
      `String` that is the default Platform user context name.

  - ### setSessionContextTimeout

    public void setSessionContextTimeout(Long sessionContextTimeoutMsec)
    Sets session context timeout given a value in units of msec.
    Parameters:
      `sessionContextTimeoutMsec` - The timeout value, in units of msec, used to destroy stale session contexts. Specify `null` to indicate that the session context will not be timed out.

  - ### setSessionContextTimeoutMinutes

    public void setSessionContextTimeoutMinutes(Long sessionContextTimeoutMinutes)
    Sets session context timeout given a value in units of minutes.
    Parameters:
      `sessionContextTimeoutMinutes` - The timeout value, in units of minutes, used to destroy stale session contexts.

  - ### convertMinutesToMsec

    public static Long convertMinutesToMsec(Long minutes)
    Converts from minutes to msec.
    Parameters:
      `minutes` - Minutes or `null`.
    Returns:
      Msec. If a `null` timeout is specified, then -1 will be returned.

  - ### getSessionContextTimeout

    public Long getSessionContextTimeout()
    Get session context timeout value in units of msec. This identifies the timeout that is used to forcibly destroy stale session contexts.
    Returns:
      `Long` the session context timeout in units of msec. A `null` indicates no timeout.

  - ### getSessionContextTimeoutMinutes

    public Long getSessionContextTimeoutMinutes()
    Get session context timeout value in units of minutes. This identifies the timeout that is used to forcibly destroy stale session contexts.
    Returns:
      `Long` the session context timeout in units of minutes. A `null` indicates no timeout.

  - ### validateServiceConfigurationCustom

    protected void validateServiceConfigurationCustom(Document document) throws ServiceConfigurationException
    Determines whether or not the service configuration is valid for this service component.
    Specified by:
      `validateServiceConfigurationCustom` in class `AbstractServiceComponentConfig`
    Parameters:
      `document` - XML document that represents a service's configuration.
    Throws:
      `ServiceConfigurationException`

  - ### appendDOM

    public DocumentFragment appendDOM(Document document)
    Appends elements to the specified XML document representing the Session Service component's configuration.
    Specified by:
      `appendDOM` in class `AbstractServiceComponentConfig`
    Parameters:
      `document` - XML document which is to be constructed by appending elements representing the Session Service configuration.
    Returns:
      XML document fragment representing an Session Service's configuration.

  - ### appendDOM

    public static DocumentFragment appendDOM(Document document, SessionServiceInitObject serviceConfig)
    Appends elements to the specified XML document representing the Session Service component's configuration.
    Parameters:
      `document` - XML document which is to be constructed by appending elements representing the Session Service configuration.
      `serviceConfig` - The Session Service configuration which is to be added to the XML document.
    Returns:
      XML document fragment representing an Session Service's configuration.

  - ### getServiceFactoryClassName

    protected String getServiceFactoryClassName()
    Gets the session service factory's fully-qualified Java class name.
    Specified by:
      `getServiceFactoryClassName` in class `AbstractServiceComponentConfig`
    Returns:
      Session service factory's fully-qualified Java class name.
    See Also:
      - `SessionServiceFactory`

  - ### removeConsumer

    public Consumer removeConsumer(Consumer consumer, boolean isRemoveResourceIfUnused) throws ServiceException
    Removes the consumer from the usage model.
    Overrides:
      `removeConsumer` in class `AbstractServiceComponentConfig`
    Parameters:
      `consumer` - Consumer whose configuration is to be removed.
      `isRemoveResourceIfUnused` - `true` if the service configuration's resources should be removed if they are no longer used by any consumers. The session context timeout and user context name will be defaulted if this parameter is set to `true` and the resource no longer used by any consumers.
    Returns:
      The removed consumer or `null`.
    Throws:
      `ServiceException` - if unable to remove the consumer.

  - ### mergeConfiguration

    protected void mergeConfiguration(AbstractServiceComponentConfig currentConfig, AbstractServiceComponentConfig newConfig) throws ServiceConfigurationException, IllegalArgumentException
    Merges the new user service configuration into the current configuration.
    Specified by:
      `mergeConfiguration` in class `AbstractServiceComponentConfig`
    Parameters:
      `currentConfig` - The current configuration into which the new configuration is to be merged.
      `newConfig` - The new configuration which is to be merged into the current configuration.
    Throws:
      `ServiceConfigurationException` - if unable to merge the service configuration.
      `IllegalArgumentException` - if a `null` current or new configuration is specified.

  - ### mergeConfiguration

    protected void mergeConfiguration(AbstractServiceComponentConfig currentConfig, AbstractServiceComponentConfig newConfig, MergePolicy mergePolicy) throws ServiceConfigurationException, IllegalArgumentException
    Merges the new user service configuration into the current configuration.
    Specified by:
      `mergeConfiguration` in class `AbstractServiceComponentConfig`
    Parameters:
      `currentConfig` - The current configuration into which the new configuration is to be merged.
      `newConfig` - The new configuration which is to be merged into the current configuration.
      `mergePolicy` - Policy which specifies how to merge service configurations.
    Throws:
      `ServiceConfigurationException` - if unable to merge the service configuration.
      `IllegalArgumentException` - if a `null` current or new configuration is specified.

  - ### addConsumer

    public Consumer addConsumer(Consumer consumer, boolean isConsumer)
    Adds the consumer to the usage model specifying its use of defined service configuration resources.

    This class overrides the superclass's implementation to clear the is consumed flag if any of the following service configuration resources are undefined.

    - User Context Name
    - Session Context Timeout
    Overrides:
      `addConsumer` in class `AbstractServiceComponentConfig`
    Parameters:
      `consumer` - The consumer to be added to the usage model.
      `isConsumer` - `true` if the consumer uses all of the service configuration's resources `false` if it uses none.
    Returns:
      The added consumer.

  - ### setIsConsumer

    public void setIsConsumer(Consumer consumer, boolean isConsumer)
    Specifies consumer use of all of the the service configuration's resources.

    This class overrides the superclass's implementation to clear the is consumed flag if any of the following service configuration resources are undefined.

    - User Context Name
    - Session Context Timeout
    Overrides:
      `setIsConsumer` in class `AbstractServiceComponentConfig`
    Parameters:
      `consumer` - The consumer.
      `isConsumer` - `true` if the consumer uses all of the service configuration's resources or `false` otherwise.

  - ### getConfig

    protected AbstractServiceComponentConfig getConfig(Document serviceConfigDocument) throws ServiceConfigurationException, IllegalArgumentException
    Gets an object representing the service's configuration data obtained from the specified XML document.
    Specified by:
      `getConfig` in class `AbstractServiceComponentConfig`
    Parameters:
      `serviceConfigDocument` - Service configuration represented as an XML document.
    Returns:
      Session Service configuration.
    Throws:
      `ServiceConfigurationException` - if unable to obtain a configuration from the specified XML document.
      `IllegalArgumentException` - if a `null` document is specified.

  - ### appendDOM

    protected DocumentFragment appendDOM(Document document, AbstractServiceComponentConfig serviceConfig) throws ServiceConfigurationException, IllegalArgumentException
    Constructs a document object model representing the configuration data for a foundation user service.
    Specified by:
      `appendDOM` in class `AbstractServiceComponentConfig`
    Parameters:
      `document` - XML document to which the service's configuration is to be appended.
      `serviceConfig` - Service configuration which is to be converted to an XML document.
    Returns:
      `null` since no child document fragments are to be added to the document.
    Throws:
      `ServiceConfigurationException` - if unable to create an XML representation of the service's configuration.
      `IllegalArgumentException` - if a `null` document or service configuration is specified.

  - ### equals

    public boolean equals(Object o)
    Determines whether or not the specified object is equivalent to this object.
    Overrides:
      `equals` in class `Object`
    Parameters:
      `o` - Object to be compared for equality.
    Returns:
      `true` if the object is a `SessionServiceInitObject` and the default user context names are equivalent.

  - ### hashCode

    public int hashCode()
    Gets the hash code.
    Overrides:
      `hashCode` in class `Object`
    Returns:
      Hash code.