Package com.sas.services

# Class AbstractServiceComponentConfig

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

All Implemented Interfaces:
  `ServiceComponentConfigInterface`, `Cloneable`

Direct Known Subclasses:
  `SessionServiceInitObject`

public abstract class AbstractServiceComponentConfig extends Object implements Cloneable, ServiceComponentConfigInterface
Abstract implementation of a foundation service component's configuration.

A concrete subclass must implement the following abstract methods:

- `getServiceFactoryClassName()` to return the fully-qualified name of the service factory's class
- `getConfig(Document document)` to obtain a service configuration from the specified XML document.
- `appendDOM(Document document, AbstractServiceComponentConfig serviceConfig)` to create an XML representation of the service configuration.
- `mergeConfig(ServiceComponent serviceComponent, Document document)` to provide an implementation that can update the service component's configuration by merging configuration data that is additive in nature (i.e. 0..* associations)
- `mergeConfiguration(AbstractServiceComponentConfig currentConfig, AbstractServiceComponentConfig newConfig)`
- `validateServiceConfigurationCustom(Document document)` to determine whether or not the specified service configuration is valid

Since:
  1.1.3

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `ENCODING`
  Service configurations are encoded using UTF-8.
  `static final String`
  `LOOKUPKEY_PROPERTYNAME_VIEWCLASS`
  The name of a property used to denote the UI view class to be used to render the service's configuration data.
  `static final String`
  `PROPERTY_NAME_INIT_DATA`
  The PropertyName of a Property used to represent the service's configuration.
  `static final String`
  `PROPERTY_NAME_INITIALIZATIONDATA`
  The PropertyName of a Property used to represent a service's configuration.
  `static final String`
  `PROPERTYROLE_APPCONFIG`
  Constant "Application Configuration" which is used in a service configuration's Property's PropertyRole to indicate that the v913 application configuration has been merged into the service's configuration.
  `static final String`
  `PROPERTYROLE_INITIALIZATION`
  Value of a metadata `StoredText`'s `Role` attribute that designates that the text string is used for initialization purposes.
  `static final String`
  `XML_ELEMENT_ATTRIBUTE_VERSION`
  XML attribute name designating the version of the configuration.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `AbstractServiceComponentConfig(InputStream configInputStream, boolean isServiceConfigurationUpdateable)`
  Constructs an instance by reading the service configuration from the specified input stream.
  `protected`
  `AbstractServiceComponentConfig(String xmlDocument)`
  Constructs a default instance.
  `protected`
  `AbstractServiceComponentConfig(String xmlDocument, boolean isServiceConfigurationUpdateable)`
  Constructs an instance specifying whether or not a service manufactured by this factory has a configuration which may be updated in an additive manner.

- ## 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.
  `protected void`
  `addResource(ConsumedResourceInterface consumedResource)`
  Adds a resource which can be used by consumers.
  `protected void`
  `addResourceAdapter(ConsumedResourceAdapter consumedResource)`
  Adds a resource which can be used by consumers.
  `protected abstract DocumentFragment`
  `appendDOM(Document document)`
  Update the XML document by appending fragments to represent the service's configuration.
  `protected abstract DocumentFragment`
  `appendDOM(Document document, AbstractServiceComponentConfig serviceConfig)`
  Constructs a document object model representing the configuration data for a foundation service.
  `Object`
  `clone()`
  Clones this configuration.
  `static final String`
  `convertDocumentToString(Document document)`
  Creates a configuration for the specified service component.
  `protected AbstractServiceComponentConfig`
  `createConfiguration(Document document)`
  Creates a service configuration initialized with the specified XML document.
  `Document`
  `createDocument(com.sas.metadata.remote.ServiceComponent serviceComponent)`
  Creates a configuration for the specified service component.
  `static final String`
  `getBaseConfigName()`
  Gets the localized name for the service's base configuration.
  `protected abstract AbstractServiceComponentConfig`
  `getConfig(Document serviceConfigDocument)`
  Gets an object representing the service's configuration data obtained from the specified XML document.
  `String`
  `getConfigName()`
  Gets the name of the configuration.
  `static String`
  `getConfigName(com.sas.metadata.remote.Property property)`
  Gets the name of the configuration from the `Name` attribute of the configuration property.
  `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.
  `ConsumedResourceAdapter`
  `getConsumedResourceAdapter(String resourceID)`
  Gets a consumed resource adapter for the specified resource ID.
  `protected final Set<String>`
  `getConsumersForResource(String resourceID)`
  Gets the set of consumer `names` that use the specified resource.
  `ConsumerUsage`
  `getConsumerUsage()`
  Gets the data describing this configuration's consumers and which resources they consume.
  `MergePolicy`
  `getDefaultMergePolicy()`
  Gets the default policy used to merge service configurations.
  `Document`
  `getDocument()`
  Creates an XML document representation of foundation service component's configuration that provides the document Element.
  `static final Properties`
  `getOutputFormatProperties()`
  Gets `OutputKeys` properties.
  `protected int`
  `getPrimeNumber()`
  Gets a prime number that can be used to compute a hash code.
  `Set<ConsumedResourceInterface>`
  `getResourcesWhichUseResource(Set<ConsumedResourceInterface> consumedResources)`
  Gets the set of resources which use the specified resource.
  `protected String[]`
  `getServiceClassIdentifiers()`
  Gets an the service's class identifiers that are valid for this configuration.
  `static final com.sas.metadata.remote.TextStore`
  `getServiceComponentConfigTextStore(com.sas.metadata.remote.ServiceComponent serviceComponent)`
  Gets the service component's configuration.
  `String`
  `getServiceComponentConfiguration(com.sas.metadata.remote.ServiceComponent serviceComponent)`
  Gets the service component's configuration.
  `static final String`
  `getServiceComponentConfigurationFromTextStore(com.sas.metadata.remote.ServiceComponent serviceComponent)`
  Gets the service component's configuration from the service's text store.
  `static final com.sas.metadata.remote.Property`
  `getServiceConfigProperty(com.sas.metadata.remote.ServiceComponent serviceComponent)`
  Gets the service component's property that represents the service's configuration data.
  `protected abstract String`
  `getServiceFactoryClassName()`
  Gets the service factory's fully-qualified Java class name.
  `protected static Document`
  `getTextStoreServiceConfig(com.sas.metadata.remote.ServiceComponent serviceComponent)`
  Gets an XML document representation of the service's configuration.
  `Set<ConsumedResourceInterface>`
  `getUnusedResources(Set<String> removedConsumerNames)`
  Gets the set of `ConsumedResourceInterface` objects representing the resources which will be unused if the specified consumers are removed.
  `com.sas.util.UsageVersion`
  `getUsageVersion()`
  Gets the usage version.
  `com.sas.util.UsageVersion`
  `getUsageVersionCurrent()`
  Gets the current usage version supported by this configuration.
  `com.sas.util.UsageVersion`
  `getUsageVersionOldest()`
  Gets the oldest usage version supported by this configuration.
  `static boolean`
  `isBaseConfig(com.sas.metadata.remote.Property property)`
  Determines if the specified property represents a service's base configuration.
  `static boolean`
  `isBaseConfiguration(com.sas.metadata.remote.Property property)`
  Determines if the specified property represents a service's base configuration.
  `final boolean`
  `isConfigurationUpdateable()`
  Determines whether or not a foundation services configuration may be updated in an additive manner.
  `protected boolean`
  `isOKToRemoveResource(String resourceID)`
  Determines if the resource is used by any consumers.
  `void`
  `mergeConfig(com.sas.metadata.remote.ServiceComponent serviceComponent, Document serviceConfiguration)`
  Merges the service's configuration by adding new service configuration to the preexisting configuration.
  `final void`
  `mergeConfigFromDocument(com.sas.metadata.remote.ServiceComponent serviceComponent, Document serviceConfiguration)`
  Merges the service's configuration by adding new service configuration to the preexisting configuration.
  `void`
  `mergeConfigFromFile(com.sas.metadata.remote.ServiceComponent serviceComponent, File file)`
  Updates the service's configuration by adding new service configuration read from the specified file to the service component's preexisting configuration.
  `void`
  `mergeConfiguration(AbstractServiceComponentConfig newConfig)`
  Merges the configuration into this configuration.
  `protected abstract void`
  `mergeConfiguration(AbstractServiceComponentConfig currentConfig, AbstractServiceComponentConfig newConfig)`
  Merges the new user service configuration into the current configuration.
  `protected abstract void`
  `mergeConfiguration(AbstractServiceComponentConfig currentConfig, AbstractServiceComponentConfig newConfig, MergePolicy mergePolicy)`
  Merges the new user service configuration into the current configuration.
  `void`
  `mergeConfiguration(AbstractServiceComponentConfig newConfig, MergePolicy mergePolicy)`
  Merges the configuration into this configuration.
  `void`
  `parseConsumerUsage(Element element)`
  Parses the "ConsumerUsage" element.
  `Document`
  `readServiceConfigFromFile(File file)`
  Read the service's configuration from the specified file.
  `protected ConsumedResourceInterface`
  `removeConsumedResource(String resourceID)`
  Removes the resource from the consumer usage model.
  `void`
  `removeConsumer(com.sas.metadata.remote.ServiceComponent serviceComponent)`
  Removes the consumer from the usage model.
  `Consumer`
  `removeConsumer(Consumer consumer, boolean isRemoveResourceIfUnused)`
  Removes the consumer from the usage model.
  `ConsumedResourceInterface`
  `removeResource(String resourceID, Set<ConsumedResourceInterface> removedConsumedResourceSet)`
  Removes the resource which can be used by consumers.
  `protected ConsumedResourceInterface`
  `removeResourceAdapter(ConsumedResourceAdapter consumedResource, Set<ConsumedResourceInterface> removedConsumedResources)`
  Adds a resource which can be used by consumers.
  `void`
  `setConfig(com.sas.metadata.remote.Property property)`
  Sets the configuration using the property's stored text configuration which contains an XML document.
  `void`
  `setConfigName(com.sas.metadata.remote.Property property)`
  Sets the name of the service configuration.
  `final void`
  `setConfigName(String configName)`
  Sets the name of the configuration.
  `void`
  `setConsumerUsage(ConsumerUsage consumerUsage)`
  Sets the data describing this configuration's consumers and which resources they consume.
  `void`
  `setIsConsumer(Consumer consumer, boolean isConsumer)`
  Specifies that the consumer uses all of the the service configuration's resources.
  `protected static final void`
  `setTextStoreServiceConfig(com.sas.metadata.remote.ServiceComponent serviceComponent, Document serviceConfigDocument)`
  Updates the service component's configuration text store with the specified service configuration.
  `void`
  `setUsageVersion(com.sas.util.UsageVersion usageVersion)`
  Sets the version.
  `protected final void`
  `setUsageVersionCompatibility(com.sas.util.UsageVersion usageVersionOldest, com.sas.util.UsageVersion usageVersionCurrent)`
  Sets the oldest version.
  `Document`
  `toDocument()`
  Creates an XML document representation of this service configuration.
  `String`
  `toXMLString()`
  Creates an XML string representation of this service's configuration.
  `protected final void`
  `validateServiceComponent(com.sas.metadata.remote.ServiceComponent serviceComponent)`
  Determines whether or not the service component is valid.
  `protected final void`
  `validateServiceConfiguration(Document document)`
  Determines whether or not the service configuration is valid for this service component.
  `protected abstract void`
  `validateServiceConfigurationCustom(Document document)`
  Determines whether or not the service configuration is valid for this service component.
  `void`
  `writeServiceConfigToFile(File file)`
  Write this service's configuration to the specified file.
  `void`
  `writeServiceConfigToFile(File file, com.sas.metadata.remote.ServiceComponent serviceComponent)`
  Write the service's configuration to the specified file.

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

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

- ## Field Details

  - ### ENCODING

    public static final String ENCODING
    Service configurations are encoded using UTF-8.
    See Also:
      - Constant Field Values

  - ### PROPERTY_NAME_INIT_DATA

    public static final String PROPERTY_NAME_INIT_DATA
    The PropertyName of a Property used to represent the service's configuration.
    See Also:
      - Constant Field Values

  - ### PROPERTY_NAME_INITIALIZATIONDATA

    public static final String PROPERTY_NAME_INITIALIZATIONDATA
    The PropertyName of a Property used to represent a service's configuration.
    See Also:
      - Constant Field Values

  - ### PROPERTYROLE_APPCONFIG

    public static final String PROPERTYROLE_APPCONFIG
    Constant "Application Configuration" which is used in a service configuration's Property's PropertyRole to indicate that the v913 application configuration has been merged into the service's configuration.
    See Also:
      - Constant Field Values

  - ### LOOKUPKEY_PROPERTYNAME_VIEWCLASS

    public static final String LOOKUPKEY_PROPERTYNAME_VIEWCLASS
    The name of a property used to denote the UI view class to be used to render the service's configuration data.
    See Also:
      - Constant Field Values

  - ### PROPERTYROLE_INITIALIZATION

    public static final String PROPERTYROLE_INITIALIZATION
    Value of a metadata `StoredText`'s `Role` attribute that designates that the text string is used for initialization purposes. This value is "initialization"
    See Also:
      - Constant Field Values

  - ### XML_ELEMENT_ATTRIBUTE_VERSION

    public static final String XML_ELEMENT_ATTRIBUTE_VERSION
    XML attribute name designating the version of the configuration.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### AbstractServiceComponentConfig

    protected AbstractServiceComponentConfig(InputStream configInputStream, boolean isServiceConfigurationUpdateable) throws IllegalArgumentException
    Constructs an instance by reading the service configuration from the specified input stream.

    Use `AbstractServiceComponentConfig(String xmlDocument, boolean isServiceConfigurationUpdateable)` to construct an instance specifying whether or not the service's configuration may be updated in an additive manner.

    Parameters:
      `configInputStream` - An input stream to a UTF-8 encoded XML document used to represent the service component's configuration.
      `isServiceConfigurationUpdateable` - `true` if the foundation service's configuration may be updated by appending new configuration data which does not conflict with another configuration.
    Throws:
      `IllegalArgumentException` - if a `null` XML document string is specified.

  - ### AbstractServiceComponentConfig

    protected AbstractServiceComponentConfig(String xmlDocument)
    Constructs a default instance.

    Use this constructor if the service manufactured by the service factory does not permit is configuration to be updated in an additive manner.

    Use `AbstractServiceComponentConfig(String xmlDocument, boolean isServiceConfigurationUpdateable)` to construct an instance specifying whether or not the service's configuration may be updated in an additive manner.

    Parameters:
      `xmlDocument` - The XML document used to represent the service component's configuration.
    Throws:
      `IllegalArgumentException` - if a `null` XML document string is specified.

  - ### AbstractServiceComponentConfig

    protected AbstractServiceComponentConfig(String xmlDocument, boolean isServiceConfigurationUpdateable)
    Constructs an instance specifying whether or not a service manufactured by this factory has a configuration which may be updated in an additive manner.

    Use `AbstractServiceComponentConfig(String xmlDocument)` to construct an instance of a factory which manufactures a service whose configuration may not be updated in an additive manner.

    Parameters:
      `xmlDocument` - The XML document used to represent the service component's configuration.
      `isServiceConfigurationUpdateable` - `true` if the foundation service's configuration may be updated by appending new configuration data which does not conflict with the another configuration.
    Throws:
      `IllegalArgumentException` - if a `null` XML document string is specified.

- ## Method Details

  - ### getConfigName

    public String getConfigName()
    Gets the name of the configuration.
    Specified by:
      `getConfigName` in interface `ServiceComponentConfigInterface`
    Returns:
      The name of this configuration.

  - ### setConfigName

    public final void setConfigName(String configName)
    Sets the name of the configuration.
    Specified by:
      `setConfigName` in interface `ServiceComponentConfigInterface`
    Parameters:
      `configName` - The name of this configuration.

  - ### getConfigName

    public static String getConfigName(com.sas.metadata.remote.Property property) throws ServiceException
    Gets the name of the configuration from the `Name` attribute of the configuration property.
    Parameters:
      `property` - Configuration property.
    Returns:
      Configuration's name.
    Throws:
      `ServiceException` - if a metadata exception occurs.

  - ### setConfigName

    public void setConfigName(com.sas.metadata.remote.Property property) throws ServiceException
    Sets the name of the service configuration.
    Parameters:
      `property` - Service configuration property.
    Throws:
      `ServiceException` - if unable to determine if the property represents the service's base configuration.

  - ### getBaseConfigName

    public static final String getBaseConfigName()
    Gets the localized name for the service's base configuration.
    Returns:
      Localized name for the service's base configuration.

  - ### isBaseConfig

    public static boolean isBaseConfig(com.sas.metadata.remote.Property property) throws ServiceException
    Determines if the specified property represents a service's base configuration.
    Parameters:
      `property` - Configuration property.
    Returns:
      `true` if the property represents the base service configuration or `false` if it represents a layered application configuration.
    Throws:
      `ServiceException` - if unable to determine if the property represents the base configuration for a service.

  - ### isBaseConfiguration

    public static boolean isBaseConfiguration(com.sas.metadata.remote.Property property) throws ServiceException
    Determines if the specified property represents a service's base configuration.
    Parameters:
      `property` - Configuration property.
    Returns:
      `true` if the property represents the base service configuration or `false` if it represents a layered application configuration.
    Throws:
      `ServiceException` - if unable to determine if the property represents the base configuration for a service.

  - ### setConfig

    public void setConfig(com.sas.metadata.remote.Property property) throws ServiceException
    Sets the configuration using the property's stored text configuration which contains an XML document.
    Parameters:
      `property` - Service configuration property.
    Throws:
      `ServiceException` - if unable to set the configuration.

  - ### createConfiguration

    protected AbstractServiceComponentConfig createConfiguration(Document document) throws ServiceException
    Creates a service configuration initialized with the specified XML document.
    Parameters:
      `document` - XML describing the service's configuration.
    Returns:
      Service configuration initialized using the XML document or `null` if a configuration is not defined.
    Throws:
      `ServiceException` - if unable to create a configuration.

  - ### getServiceConfigProperty

    public static final com.sas.metadata.remote.Property getServiceConfigProperty(com.sas.metadata.remote.ServiceComponent serviceComponent) throws ServiceException
    Gets the service component's property that represents the service's configuration data.
    Parameters:
      `serviceComponent` - Service component whose configuration data property is desired.
    Returns:
      Service component's property that represents the service's configuration data or `null` if a property is not defined.
    Throws:
      `ServiceException` - if unable to query the service component's properties.

  - ### isConfigurationUpdateable

    public final boolean isConfigurationUpdateable()
    Determines whether or not a foundation services configuration may be updated in an additive manner. A service which supports an additive configuration allows one to update the current configuration with additional configuration data, so long as the added configuration does not conflict with the preexisting configuration.
    Specified by:
      `isConfigurationUpdateable` in interface `ServiceComponentConfigInterface`
    Returns:
      `true` if the foundation service's configuration may be updated by appending new configuration data which does not conflict with the preexisting configuration.

  - ### validateServiceComponent

    protected final void validateServiceComponent(com.sas.metadata.remote.ServiceComponent serviceComponent) throws ServiceConfigurationException, IllegalArgumentException
    Determines whether or not the service component is valid.
    Parameters:
      `serviceComponent` - The service component whose configuration data is to be updated.
    Throws:
      `ServiceConfigurationException` - if an invalid service component is specified.
      `IllegalArgumentException` - if a `null` service component is specified.

  - ### validateServiceConfiguration

    protected final void validateServiceConfiguration(Document document) throws ServiceException, IllegalArgumentException
    Determines whether or not the service configuration is valid for this service component.
    Parameters:
      `document` - XML document representing a service's configuration.
    Throws:
      `ServiceException` - if an invalid configuration is specified.
      `IllegalArgumentException` - if a `null` service configuration is specified.

  - ### getServiceClassIdentifiers

    protected String[] getServiceClassIdentifiers()
    Gets an the service's class identifiers that are valid for this configuration. A subclass should override this method if a class identifier other than `RemoteServiceInterface.CLASS_IDENTIFIER` is employed.
    Returns:
      Service's class identifier.

  - ### mergeConfigFromDocument

    public final void mergeConfigFromDocument(com.sas.metadata.remote.ServiceComponent serviceComponent, Document serviceConfiguration) throws ServiceException
    Merges the service's configuration by adding new service configuration to the preexisting configuration.

    A subclass should override this method if it allows configuration data to be merged into a preexisting configuration.

    Parameters:
      `serviceComponent` - The service whose configuration is to be updated.
      `serviceConfiguration` - The service configuration to be added to the service's current configuration. Note that only configuration data that is additive in nature can be appended. Configuration data that is non-additive will be ignored.
    Throws:
      `ServiceException` - if unable to update the service's configuration.
      `IllegalArgumentException` - if a `null` service component or service configuration is specified.

  - ### mergeConfiguration

    public void mergeConfiguration(AbstractServiceComponentConfig newConfig) throws ServiceConfigurationException, IllegalArgumentException
    Merges the configuration into this configuration.
    Parameters:
      `newConfig` - The configuration that is to be merged into this configuration.
    Throws:
      `ServiceConfigurationException` - if unable to merge the configuration.
      `IllegalArgumentException` - if an invalid parameter is specified.

  - ### mergeConfiguration

    public void mergeConfiguration(AbstractServiceComponentConfig newConfig, MergePolicy mergePolicy) throws ServiceConfigurationException, IllegalArgumentException
    Merges the configuration into this configuration.
    Parameters:
      `newConfig` - The configuration that is to be merged into this configuration.
      `mergePolicy` - Policy which specifies how conflicts will be handled.
    Throws:
      `ServiceConfigurationException` - if unable to merge the configuration.
      `IllegalArgumentException` - if an invalid parameter is specified.

  - ### mergeConfiguration

    protected abstract void mergeConfiguration(AbstractServiceComponentConfig currentConfig, AbstractServiceComponentConfig newConfig) throws ServiceConfigurationException, IllegalArgumentException
    Merges the new user service configuration into the current configuration.
    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 abstract void mergeConfiguration(AbstractServiceComponentConfig currentConfig, AbstractServiceComponentConfig newConfig, MergePolicy mergePolicy) throws ServiceConfigurationException, IllegalArgumentException
    Merges the new user service configuration into the current configuration.
    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 conflicts will be handled.
    Throws:
      `ServiceConfigurationException` - if unable to merge the service configuration.
      `IllegalArgumentException` - if a `null` current or new configuration is specified.

  - ### appendDOM

    protected abstract DocumentFragment appendDOM(Document document, AbstractServiceComponentConfig serviceConfig) throws ServiceConfigurationException, IllegalArgumentException
    Constructs a document object model representing the configuration data for a foundation service.
    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.

  - ### validateServiceConfigurationCustom

    protected abstract void validateServiceConfigurationCustom(Document document) throws ServiceException
    Determines whether or not the service configuration is valid for this service component.
    Parameters:
      `document` - XML document that represents a service's configuration.
    Throws:
      `ServiceException` - if an invalid configuration is specified.

  - ### getDocument

    public Document getDocument() throws ServiceException
    Creates an XML document representation of foundation service component's configuration that provides the document Element.
    Specified by:
      `getDocument` in interface `ServiceComponentConfigInterface`
    Returns:
      Foundation service configuration document.
    Throws:
      `ServiceException` - if unable to create a document.

  - ### convertDocumentToString

    public static final String convertDocumentToString(Document document) throws ServiceException
    Creates a configuration for the specified service component.
    Parameters:
      `document` - XML document representation for a service's configuration.
    Returns:
      Service configuration or `null` if a document is not available.
    Throws:
      `ServiceException` - if unable to create an XML document representation of the service configuration.

  - ### getOutputFormatProperties

    public static final Properties getOutputFormatProperties()
    Gets `OutputKeys` properties.
    Returns:
      Output format properties.

  - ### createDocument

    public Document createDocument(com.sas.metadata.remote.ServiceComponent serviceComponent) throws ServiceException
    Creates a configuration for the specified service component.
    Specified by:
      `createDocument` in interface `ServiceComponentConfigInterface`
    Parameters:
      `serviceComponent` - Service component's which will be queried for an XML configuration stored in an configuration property text store.
    Returns:
      Service configuration or `null` if a document is not available.
    Throws:
      `ServiceException` - if unable to create an XML document representation of the service configuration.

  - ### getServiceFactoryClassName

    protected abstract String getServiceFactoryClassName()
    Gets the service factory's fully-qualified Java class name.
    Returns:
      Service factory's fully-qualified Java class name.

  - ### getConfig

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

  - ### mergeConfig

    public void mergeConfig(com.sas.metadata.remote.ServiceComponent serviceComponent, Document serviceConfiguration) throws ServiceException
    Merges the service's configuration by adding new service configuration to the preexisting configuration.
    Parameters:
      `serviceComponent` - The service whose configuration is to be merged with the specified configuration.
      `serviceConfiguration` - The service configuration to be added to the service's current configuration. Note that only configuration data that is additive in nature can be appended. Configuration data that is non-additive will be ignored.
    Throws:
      `ServiceException` - if unable to update the service's configuration.
      `IllegalArgumentException` - if a `null` service component or service configuration is specified.

  - ### mergeConfigFromFile

    public void mergeConfigFromFile(com.sas.metadata.remote.ServiceComponent serviceComponent, File file) throws ServiceException
    Updates the service's configuration by adding new service configuration read from the specified file to the service component's preexisting configuration.
    Specified by:
      `mergeConfigFromFile` in interface `ServiceComponentConfigInterface`
    Parameters:
      `serviceComponent` - The service whose configuration is to be updated.
      `file` - File containing the service configuration which is to be added to the service component's current configuration. Note that only configuration data that is additive in nature can be appended. Configuration data that is non-additive will be ignored.
    Throws:
      `ServiceException` - if unable to update the service's configuration.
      `IllegalArgumentException` - if a `null` service component or file is specified.

  - ### readServiceConfigFromFile

    public Document readServiceConfigFromFile(File file) throws ServiceException
    Read the service's configuration from the specified file.
    Parameters:
      `file` - File to which the service's configuration is to be written using UTF-8 encoding.
    Returns:
      XML Document read from the file.
    Throws:
      `ServiceException` - if an exception was encountered persisting the service's configuration to a file.
      `IllegalArgumentException` - if a `null` file is specified.

  - ### writeServiceConfigToFile

    public void writeServiceConfigToFile(File file) throws ServiceException
    Write this service's configuration to the specified file.
    Parameters:
      `file` - File to which the service's configuration is to be written using UTF-8 encoding.
    Throws:
      `ServiceException` - if an exception was encountered persisting the service's configuration to a file.
      `IllegalArgumentException` - if a `null` file is specified.

  - ### writeServiceConfigToFile

    public void writeServiceConfigToFile(File file, com.sas.metadata.remote.ServiceComponent serviceComponent) throws ServiceException
    Write the service's configuration to the specified file.
    Specified by:
      `writeServiceConfigToFile` in interface `ServiceComponentConfigInterface`
    Parameters:
      `file` - File to which the service's configuration is to be written using UTF-8 encoding.
      `serviceComponent` - Service component whose configuration is to be written to the specified file.
    Throws:
      `ServiceException` - if an exception was encountered persisting the service's configuration to a file.
      `IllegalArgumentException` - if a `null` service component or file is specified.

  - ### getServiceComponentConfiguration

    public String getServiceComponentConfiguration(com.sas.metadata.remote.ServiceComponent serviceComponent) throws ServiceException
    Gets the service component's configuration.

    This implementation locates the service component's property named `"INIT_DATA"` and then obtains the property's stored text configuration.

    If a service persists its configuration data in another manner, then this method should be overridden to provide an appropriate mechanism to obtain the service's configuration.

    Parameters:
      `serviceComponent` - Service whose configuration is to be obtained.
    Returns:
      Service's configuration.
    Throws:
      `ServiceException` - if unable to obtain the service's configuration.

  - ### getServiceComponentConfigurationFromTextStore

    public static final String getServiceComponentConfigurationFromTextStore(com.sas.metadata.remote.ServiceComponent serviceComponent) throws ServiceException
    Gets the service component's configuration from the service's text store.

    This implementation locates the service component's property named `PROPERTY_NAME_INIT_DATA`, verifies that the property's text role is `PROPERTYROLE_INITIALIZATION`, and then obtains the property's stored text configuration.

    Parameters:
      `serviceComponent` - Service whose configuration is to be obtained.
    Returns:
      Service's configuration.
    Throws:
      `ServiceException` - if unable to obtain the service's configuration.

  - ### getServiceComponentConfigTextStore

    public static final com.sas.metadata.remote.TextStore getServiceComponentConfigTextStore(com.sas.metadata.remote.ServiceComponent serviceComponent) throws ServiceException
    Gets the service component's configuration.

    This implementation locates the service component's property named `PROPERTY_NAME_INIT_DATA`, verifies that the property's text role is `PROPERTYROLE_INITIALIZATION`, and then obtains the property's stored text configuration.

    If a service persists its configuration data in another manner, then this method should be overridden to provide an appropriate mechanism to obtain the service's configuration.

    Parameters:
      `serviceComponent` - Service whose configuration is to be obtained.
    Returns:
      Service's configuration text store.
    Throws:
      `ServiceException` - if unable to obtain the service's configuration.

  - ### getConsumedResourceAdapter

    public ConsumedResourceAdapter getConsumedResourceAdapter(String resourceID)
    Gets a consumed resource adapter for the specified resource ID.
    Parameters:
      `resourceID` - ID of the consumed resource whose adapter is to be returned.
    Returns:
      Consumed resource adapter for the specified resource.

  - ### clone

    public Object clone() throws CloneNotSupportedException
    Clones this configuration.
    Overrides:
      `clone` in class `Object`
    Returns:
      Clone of this configuration.
    Throws:
      `CloneNotSupportedException` - if cloning is not supported.

  - ### getTextStoreServiceConfig

    protected static Document getTextStoreServiceConfig(com.sas.metadata.remote.ServiceComponent serviceComponent) throws ServiceException
    Gets an XML document representation of the service's configuration. This implementation reads the stored text associated with a service component property named `PROPERTY_NAME_INIT_DATA`.

    A subclass should override this method if it does not persist its configuration using the `PROPERTY_NAME_INIT_DATA` property of the service component.

    Parameters:
      `serviceComponent` - The service component from which an XML document representation of its configuration is to be obtained.
    Returns:
      XML document representation of the service's configuration.
    Throws:
      `ServiceException` - if unable to obtain an XML document representation of the service's configuration.

  - ### setTextStoreServiceConfig

    protected static final void setTextStoreServiceConfig(com.sas.metadata.remote.ServiceComponent serviceComponent, Document serviceConfigDocument) throws ServiceException
    Updates the service component's configuration text store with the specified service configuration.
    Parameters:
      `serviceComponent` - The service whose text store is to be updated with the specified service configuration.
      `serviceConfigDocument` - Service configuration to be assigned to the service component's text store.
    Throws:
      `ServiceException` - if unable to assign the service configuration.

  - ### getUsageVersion

    public com.sas.util.UsageVersion getUsageVersion()
    Gets the usage version.
    Returns:
      Configuration's version.

  - ### getUsageVersionCurrent

    public com.sas.util.UsageVersion getUsageVersionCurrent()
    Gets the current usage version supported by this configuration.
    Returns:
      Configuration's version.

  - ### getUsageVersionOldest

    public com.sas.util.UsageVersion getUsageVersionOldest()
    Gets the oldest usage version supported by this configuration.
    Returns:
      Configuration's version.

  - ### setUsageVersion

    public void setUsageVersion(com.sas.util.UsageVersion usageVersion) throws IllegalArgumentException
    Sets the version.
    Parameters:
      `usageVersion` - Configuration's version.
    Throws:
      `IllegalArgumentException` - if a `null` or incompatible usage version is specified.

  - ### setUsageVersionCompatibility

    protected final void setUsageVersionCompatibility(com.sas.util.UsageVersion usageVersionOldest, com.sas.util.UsageVersion usageVersionCurrent) throws IllegalArgumentException
    Sets the oldest version.
    Parameters:
      `usageVersionOldest` - Configuration's oldest supported version.
      `usageVersionCurrent` - Configuration's currently supported version.
    Throws:
      `IllegalArgumentException` - if a `null` or incompatible usage version is specified.

  - ### 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.

    A sub-class should override this method if it wants to use a different message.

    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.

    A sub-class should override this method if it wants to use a different message.

    Parameters:
      `consumedResource` - The consumed resource which is being removed.
    Returns:
      Localized confirm delete message.

  - ### getPrimeNumber

    protected int getPrimeNumber()
    Gets a prime number that can be used to compute a hash code.
    Returns:
      Prime number.

  - ### toDocument

    public Document toDocument() throws ServiceException
    Creates an XML document representation of this service configuration.
    Returns:
      XML document representation of this service configuration.
    Throws:
      `ServiceException` - if unable to create an XML document representation of this service configuration.

  - ### toXMLString

    public String toXMLString() throws ServiceException
    Creates an XML string representation of this service's configuration.
    Returns:
      XML string representation of this service's configuration or `null` if there is no XML document representation of the configuration.
    Throws:
      `ServiceException` - if unable to create an XML string.

  - ### appendDOM

    protected abstract DocumentFragment appendDOM(Document document) throws ServiceException
    Update the XML document by appending fragments to represent the service's configuration.
    Parameters:
      `document` - XML document to which document fragments are to be appended.
    Returns:
      The XML document fragment or `null` if no fragment was appended.
    Throws:
      `ServiceException` - if unable to construct the XML document.

  - ### parseConsumerUsage

    public void parseConsumerUsage(Element element)
    Parses the "ConsumerUsage" element.
    Parameters:
      `element` - "ConsumerUsage" XML element.

  - ### getConsumerUsage

    public ConsumerUsage getConsumerUsage()
    Gets the data describing this configuration's consumers and which resources they consume.
    Returns:
      Consumer usage model.

  - ### setConsumerUsage

    public void setConsumerUsage(ConsumerUsage consumerUsage)
    Sets the data describing this configuration's consumers and which resources they consume.
    Parameters:
      `consumerUsage` - Consumer usage.

  - ### addConsumer

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

    A sub-class can override this method if it needs to implement custom logic to specify that only some of the service configuration's resources are used by the consumer.

    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.

  - ### removeConsumer

    public Consumer removeConsumer(Consumer consumer, boolean isRemoveResourceIfUnused) throws ServiceException
    Removes the consumer from the usage model.
    Parameters:
      `consumer` - The 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.
    Returns:
      The removed consumer or `null`.
    Throws:
      `ServiceException` - if an error occurs while attempting to remove the consumer.

  - ### removeConsumer

    public void removeConsumer(com.sas.metadata.remote.ServiceComponent serviceComponent) throws ServiceException
    Removes the consumer from the usage model.
    Parameters:
      `serviceComponent` - Remove current consumer from this serviceComponent.
    Throws:
      `ServiceException` - if an error occurs while attempting to remove the consumer.

  - ### getUnusedResources

    public Set<ConsumedResourceInterface> getUnusedResources(Set<String> removedConsumerNames)
    Gets the set of `ConsumedResourceInterface` objects representing the resources which will be unused if the specified consumers are removed.

    A service configuration which has resources which depend upon other resources should implement this method to ensure its integrity by only returning the set of resources which are not used by any consumer or resource.

    Parameters:
      `removedConsumerNames` - Set of `String` removed consumer names.
    Returns:
      Set of `ConsumedResourceInterface` representing resources which will be unused if the specified consumers are removed. An empty set will be returned otherwise.

  - ### isOKToRemoveResource

    protected boolean isOKToRemoveResource(String resourceID)
    Determines if the resource is used by any consumers.

    A sub-class can override this method if it needs to control whether a resource can be removed based on its use by other resources.

    Parameters:
      `resourceID` - The ID of the resource which will be removed from the model if this service configuration says that it is not used.
    Returns:
      `true` indicating that it is OK to remove this resource. A sub-class can override this method if it needs to control whether a resource can be removed based on its use by other resources.

  - ### getConsumersForResource

    protected final Set<String> getConsumersForResource(String resourceID)
    Gets the set of consumer `names` that use the specified resource.
    Parameters:
      `resourceID` - Resource's ID.
    Returns:
      Set containing the `String` names of consumers that use the specified resource. An empty set will be returned if the resource is not used by any consumers.

  - ### setIsConsumer

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

    A sub-class can override this method if it needs to implement custom logic to specify that only some of the service configuration's resources are used by the consumer.

    Parameters:
      `consumer` - The consumer.
      `isConsumer` - `true` if the consumer uses all of the service configuration's resources or `false` otherwise.

  - ### addResourceAdapter

    protected void addResourceAdapter(ConsumedResourceAdapter consumedResource)
    Adds a resource which can be used by consumers.
    Parameters:
      `consumedResource` -

  - ### removeResourceAdapter

    protected ConsumedResourceInterface removeResourceAdapter(ConsumedResourceAdapter consumedResource, Set<ConsumedResourceInterface> removedConsumedResources) throws ServiceException
    Adds a resource which can be used by consumers.
    Parameters:
      `consumedResource` - Consumed resource which is to be removed.
      `removedConsumedResources` - Set of consumed resources which have been removed.
    Returns:
      The removed consumed resource adapter.
    Throws:
      `ServiceException` - if unable to remove the resource adapter.

  - ### addResource

    protected void addResource(ConsumedResourceInterface consumedResource)
    Adds a resource which can be used by consumers.
    Parameters:
      `consumedResource` -

  - ### removeResource

    public ConsumedResourceInterface removeResource(String resourceID, Set<ConsumedResourceInterface> removedConsumedResourceSet) throws ServiceException
    Removes the resource which can be used by consumers.

    A sub-class must implement this method to provide logic to remove the resource from its configuration and then call this method to remove the resource from the consumer usage model.

    Parameters:
      `resourceID` - The unique ID of the resource which is to be removed from the consumer usage model.
      `removedConsumedResourceSet` - Set of `ConsumedResourceInterface` objects which have been removed.
    Returns:
      The removed `ConsumedResourceInterface` object or `null` if the resource was not defined.
    Throws:
      `ServiceException` - if unable to remove a resource.

  - ### removeConsumedResource

    protected ConsumedResourceInterface removeConsumedResource(String resourceID)
    Removes the resource from the consumer usage model.

    A sub-class must implement this method to provide logic to remove the resource from its configuration and then call this method to remove the resource from the consumer usage model.

    Parameters:
      `resourceID` - The unique ID of the resource which is to be removed from the consumer usage model.
    Returns:
      The removed `ConsumedResourceInterface` object or `null` if the resource was not defined.

  - ### getResourcesWhichUseResource

    public Set<ConsumedResourceInterface> getResourcesWhichUseResource(Set<ConsumedResourceInterface> consumedResources)
    Gets the set of resources which use the specified resource.

    A sub-class should override this method if any of the service configuration's resources depend on each other.

    Parameters:
      `consumedResources` - Set of `ConsumedResourceInterface` for which we need to identify the resources which use it.
    Returns:
      Set of `ConsumedResourceInterface` or an empty set if no resource depends on the specified resources.

  - ### getDefaultMergePolicy

    public MergePolicy getDefaultMergePolicy()
    Gets the default policy used to merge service configurations.
    Returns:
      Policy which specifies that the merge should be rejected in the event that a conflict is encountered.