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

Package com.sas.services.deployment

# Class ServiceDeploymentImporter

java.lang.Object
java.lang.Thread
com.sas.services.deployment.ServiceDeploymentImporter

All Implemented Interfaces:
  `Runnable`

@SASScope("ALL") @BinaryCompatibilityOnly public final class ServiceDeploymentImporter extends Thread
Utility to import metadata representing a SAS Foundation Services deployment from a UTF-8 encoded XML file into a SAS Metadata Repository.

Construct an instance of this utility by specifying the metadata XML which is to be imported into a SAS Metadata Repository.

Use the following approach to import metadata describing a SAS Foundation Services deployment from a file into a metadata object store.

Usage Example: Static Invocation
     import com.sas.metadata.remote.MdStore;
     ...

     try {

       // use a metadata store which has been initialized with a connection
       // to the metadata server
       final MdStore mdStore = ...;

       // specify the file containing the foundation services deployment
       // metadata created using the Foundation Services Manager plug-in.
       final File file = new File(filePath);

       // import the service deployment metadata from the file
       // into the specified SAS Metadata Repository
       // specified by the fully qualified SAS Metadata Repository ID
       ServiceDeploymentImporter.importServiceDeploymentFromFile(
          new ServiceDeploymentImportFile(file),
          repositoryID,
          mdStore);
     }
     catch (IllegalArgumentException e) {
       // an invalid file has been specified
     }
     catch (NameNotUniqueImportException e) {
       // service deployment name (SoftwareComponent.Name) is not unique
     }
     catch (ServiceDeploymentImportException e) {
       // handle exception
     }

Use the following approach to asynchronous import metadata describing a SAS Foundation Services deployment from a UTF-8 encoded XML file into a metadata object store. An operation monitor should be specified, so that it can be notified if an exception occurs.

Usage Example: Asynchronous Import
     import com.sas.metadata.remote.MdStore;
     ...

     try {

        // use a metadata store which has been initialized with a connection
        // to the metadata server
        final MdStore mdStore = ...;

        // specify the file containing the foundation services deployment
        // metadata created using the Foundation Services Manager plug-in
        // and the fully qualified SAS Metadata Repository ID.
        final File file = new File(filePath);

        // import the service deployment metadata from the file
        // into the specified SAS Metadata Repository.
        final OperationMonitorInterface optionalMonitor = null;
        final ServiceDeploymentImporter serviceDeploymentImporter =
           new ServiceDeploymentImporter(
              repositoryID,
              new ServiceDeploymentImportFile(file),
              optionalMonitor,
              mdStore.getFactory());

        // asynchronously import the services deployment in a background thread.
        // if a monitor is specified it will be notified if any
        // exceptions were encountered
        serviceDeploymentImporter.start();

     }
     catch (IllegalArgumentException e) {
        // an invalid file has been specified
     }
     catch (NameNotUniqueImportException e) {
        // service deployment name (SoftwareComponent.Name) is not unique
     }
     catch (ServiceDeploymentImportException e) {
        // handle exception
     }

Use the following approach to synchronously import metadata describing a SAS Foundation Services deployment from a file into a metadata object store. An operation monitor should be specified, so that it can be notified if an exception occurs.

Usage Example: Synchronous Import
     import com.sas.metadata.remote.MdStore;
     ...

     try {

       // use a metadata store which has been initialized with a connection
       // to the metadata server
       final MdStore mdStore = ...;

       // specify the file containing the foundation services deployment
       // metadata created using the Foundation Services Manager plug-in
       // and the fully qualified SAS Metadata Repository ID.
       final File file = new File(filePath);

       // monitor or null if operation is not being monitored
       final OperationMonitorInterface optionalMonitor = ...;

       // import the service deployment metadata from the file
       // into the specified SAS Metadata Repository.
       final ServiceDeploymentImporter serviceDeploymentImporter =
          new ServiceDeploymentImporter(
             repositoryID,
             new ServiceDeploymentImportFile(file),
             optionalMonitor,
             mdStore.getFactory());

       // synchronously import the services deployment in a background thread.
       // if a monitor is specified it will be notified if any
       // exceptions were encountered
       serviceDeploymentImporter.run();

     }
     catch (IllegalArgumentException e) {
       // an invalid file has been specified
     }
     catch (NameNotUniqueImportException e) {
       // service deployment name (SoftwareComponent.Name) is not unique
     }
     catch (ServiceDeploymentImportException e) {
       // handle exception
     }

Use the following approach to import metadata describing a SAS Foundation Services deployment from a `String` into a metadata object store.

Usage Example: Import SAS Foundation Services Deployment Using XML String
     import com.sas.metadata.remote.MdStore;
     ...

     try {

      // use a metadata store which has been initialized with a connection
      // to the metadata server
      final MdStore mdStore = ...;

      // use a string representation of the XML that describes the
      // foundation services deployment
      final String servicesDeploymentXML = getServicesDeploymentAsXML();

      // specifies whether the services deployment XML is well formed.
      // if false, the XML will be wrapped in an XML element to make
      // it well formed.
      final boolean isWellFormedXML = false;

      // import the service deployment metadata from the file
      // into the specified SAS Metadata Repository.
      ServiceDeploymentImporter.importServiceDeployment(
         servicesDeploymentXML,
         mdStore,
         isWellFormedXML);

     }
     catch (NameNotUniqueImportException e) {
       // service deployment name (SoftwareComponent.Name) is not unique
     }
     catch (ServiceDeploymentImportException e) {
       // handle exception
     }

Since:
  1.0

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class java.lang.Thread

  `Thread.Builder, Thread.State, Thread.UncaughtExceptionHandler`

- ## Field Summary

  ### Fields inherited from class java.lang.Thread

  `MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ServiceDeploymentImporter(String repositoryId, ServiceDeploymentImportFile serviceDeploymentImportFile, OperationMonitorInterface operationMonitor, com.sas.metadata.remote.MdFactory mdFactory)`
  Constructs an instance of a runnable service deployment importer which will use the remote JOMA API.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `dispose()`
  Destroys this import utility releasing any resources that may have been allocated.
  `static void`
  `importDeployment(String[] args)`
  Method for an application which is used to import metadata describing a SAS Foundation Service deployment from a UTF-8 encoded XML file into a SAS Metadata Repository.
  `static void`
  `importServiceDeployment(com.sas.metadata.remote.MdStore mdStore, ServiceDeploymentImportFile serviceDeploymentImportFile, String repositoryName)`
  Imports a SAS Foundation Services deployment from a UTF-8 encoded SAS Foundation Services deployment XML file into the SAS Metadata Repository.
  `static void`
  `importServiceDeployment(String metadata, com.sas.metadata.remote.MdStore mdStore, boolean isWellFormed)`
  Populates the object store with the specified metadata.
  `static void`
  `importServiceDeploymentFromFile(ServiceDeploymentImportFile serviceDeploymentImportFile, String metadataRepositoryID, com.sas.metadata.remote.MdStore mdStore)`
  Imports metadata describing a SAS Foundation Services deployment configuration from a file into the metadata object store.
  `static void`
  `main(String[] args)`
  `void`
  `run()`
  Runs the SAS Foundation Services deployment importer to load an metadata into a SAS Metadata Repository.
  `static void`
  `verifyDeploymentIsImportable(String repositoryId, String serviceDeploymentName, com.sas.metadata.remote.MdStore mdStore)`
  Constructs an `XMLSelect` based upon the specified software component(s) which represent SAS Foundation Services deployments.
  `static void`
  `verifyServiceDeploymentsAreImportable(String repositoryId, Set<String> serviceDeploymentsToImport, com.sas.metadata.remote.MdStore mdStore)`
  Constructs an `XMLSelect` based upon the specified software component(s) which represent SAS Foundation Services deployments.

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

  `activeCount, checkAccess, clone, countStackFrames, currentThread, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, isVirtual, join, join, join, join, ofPlatform, ofVirtual, onSpinWait, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, sleep, start, startVirtualThread, stop, suspend, threadId, toString, yield`

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

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

- ## Constructor Details

  - ### ServiceDeploymentImporter

    public ServiceDeploymentImporter(String repositoryId, ServiceDeploymentImportFile serviceDeploymentImportFile, OperationMonitorInterface operationMonitor, com.sas.metadata.remote.MdFactory mdFactory) throws IllegalArgumentException
    Constructs an instance of a runnable service deployment importer which will use the remote JOMA API. The caller is responsible for ensuring that the JOMA metadata factory is connected to the destination SAS Metadata Repository.

    Metadata representing a foundation services deployment will be read from a foundation services deployment file and imported into a SAS Metadata Repository when the `run()` method is invoked.

    Note that the caller is responsible for destroying this utility by invoking `dispose()` to release any resources allocated by this importer after the import has been executed.

    Parameters:
      `repositoryId` - SAS Metadata Repository ID.
      `serviceDeploymentImportFile` - A file containing importable foundation service deployment metadata.
      `operationMonitor` - An operation monitor or `null` if the operation won't be monitored.
      `mdFactory` - Metadata factory with a connection to the SAS Metadata Server.
    Throws:
      `IllegalArgumentException` - if unable to construct an instance due to invalid parameters.
    Since:
      9.2

- ## Method Details

  - ### run

    public void run()
    Runs the SAS Foundation Services deployment importer to load an metadata into a SAS Metadata Repository.

    If an operation monitor is specified, then it will be run to notify the caller of the completion status of the import operation.

    Specified by:
      `run` in interface `Runnable`
    Overrides:
      `run` in class `Thread`
    Since:
      1.0
    See Also:
      - `Runnable.run()`

  - ### importServiceDeploymentFromFile

    public static void importServiceDeploymentFromFile(ServiceDeploymentImportFile serviceDeploymentImportFile, String metadataRepositoryID, com.sas.metadata.remote.MdStore mdStore) throws ServiceDeploymentImportException
    Imports metadata describing a SAS Foundation Services deployment configuration from a file into the metadata object store.

    The service deployment import occurs within a a synchronized code block to serialize access to ensure that a new deployment is verified for uniqueness.

    Parameters:
      `serviceDeploymentImportFile` - UTF-8 encoded file containing metadata that is to be imported into the metadata repository.
      `metadataRepositoryID` - The ID of the SAS Metadata Repository to which the service deployment metadata is to be imported.
      `mdStore` - Metadata store initialized with a factory that has a connection to the metadata server.
    Throws:
      `ServiceDeploymentImportException` - if unable to import SAS Foundation Services deployment metadata from the file into a SAS Metadata Repository specified by the active workspace.
    Since:
      9.2

  - ### importServiceDeployment

    public static void importServiceDeployment(String metadata, com.sas.metadata.remote.MdStore mdStore, boolean isWellFormed) throws ServiceDeploymentImportException
    Populates the object store with the specified metadata.
    Parameters:
      `metadata` - Metadata that is to be populated into the metadata object store.
      `mdStore` - Metadata store initialized with a factory which has a connection to the metadata server.
      `isWellFormed` - `false` if the specified metadata XML needs a root element in order to be well formed or `true` if the metadata XML already has a root element.
    Throws:
      `ServiceDeploymentImportException` - if unable to import the SAS Foundation Services deployment into the SAS Metadata Repository.
    Since:
      9.2

  - ### verifyDeploymentIsImportable

    public static void verifyDeploymentIsImportable(String repositoryId, String serviceDeploymentName, com.sas.metadata.remote.MdStore mdStore) throws ServiceDeploymentImportException
    Constructs an `XMLSelect` based upon the specified software component(s) which represent SAS Foundation Services deployments. Only `SoftwareComponent` elements with a ClassIdentifier value representing a SAS Foundation Services deployment will be selected. If the set is non-empty then only those `SoftwareComponent` elements will be selected based on a matching Name value.
    Parameters:
      `repositoryId` - The ID of the SAS Metadata Repository to which the service deployment metadata is to be imported.
      `serviceDeploymentName` - The name of the SAS Foundation Services deployment which is to be imported.
      `mdStore` - Metadata store initialized with a factory that has a connection to the metadata server.
    Throws:
      `ServiceDeploymentImportException` - if one or more SAS Foundation Services deployments which are candidates for import into the metadata repository are already defined.
      `IllegalArgumentException` - if a `null` parameter or invalid service deployment name is specified.
    Since:
      9.2

  - ### verifyServiceDeploymentsAreImportable

    public static void verifyServiceDeploymentsAreImportable(String repositoryId, Set<String> serviceDeploymentsToImport, com.sas.metadata.remote.MdStore mdStore) throws ServiceDeploymentImportException
    Constructs an `XMLSelect` based upon the specified software component(s) which represent SAS Foundation Services deployments. Only `SoftwareComponent` elements with a ClassIdentifier value representing a SAS Foundation Services deployment will be selected. If the set is non-empty then only those `SoftwareComponent` elements will be selected based on a matching Name value.
    Parameters:
      `repositoryId` - The ID of the SAS Metadata Repository to which the SAS Foundation Services deployment metadata is to be imported.
      `serviceDeploymentsToImport` - Set of metadata `String` elements representing the names of the SAS Foundation Services deployments that are to be imported.
      `mdStore` - Metadata store initialized with a factory that has a connection to the metadata server.
    Throws:
      `ServiceDeploymentImportException` - if one or more SAS Foundation Services deployments which are candidates for import into the repository are already defined.
    Since:
      1.0

  - ### dispose

    public void dispose()
    Destroys this import utility releasing any resources that may have been allocated.
    Since:
      1.0

  - ### main

    public static void main(String[] args)

  - ### importDeployment

    public static void importDeployment(String[] args) throws ServiceException
    Method for an application which is used to import metadata describing a SAS Foundation Service deployment from a UTF-8 encoded XML file into a SAS Metadata Repository. Command line options used to run this application are summarized below.

    ## SAS Foundation Service

    When importing a SAS Foundation Services deployment from a file into a SAS Metadata Server, one must identify the file that contains the services deployment metadata to be imported. This file can be created by the Foundation Services Manager plug-in to the SAS Management Console by exporting a services deployment.

    Optionally, one may also specify a new name for the service deployment that is to be created in the SAS Metadata Server. The name specified in the services deployment file is not affected.

    SAS Foundation Service Command Line Options
    SAS Foundation Services
    Option | Description
    --- | ---
    `-serviceDeploymentFile` | File that contains a UTF-8 encoded SAS Foundation Service deployment which is to be imported into the SAS Metadata Server. The Foundation Services Manager plug-in to the SAS Management Console is used to export metadata describing a services deployment to a file.
    `-serviceDeploymentName` | Optional new name for the SAS Foundation Services deployment (SoftwareComponent.Name). If unspecified, then the name of the services deployment defined in the file will be used.

    ## Metadata Server

    One must specify the SAS Metadata Server and the desired connection approach.

    Parameters:
      `args` - Command line arguments specifying the metadata server, the name of the services deployment file to be imported and the login ID and password needed to open a connection to the server.
      - -metaserver <server>
      - -metaport <port>
      - -metarepository <repository>
      - -serviceDeploymentFile <serviceDeploymentFile>
      - -serviceDeploymentName <serviceDeploymentName> (optional, specify if an alternative SoftwareComponent.Name is desired)
      - Connection
        - using a Login Credential
          - -metauser <userID>
          - -metapass <password> or -password_on_stdin <true> (and specify -metapass via stdin)
        - using SSPI
          - -secpackagelist <secpackagelist>
          - -metaspn <spn> (optional)

      One may optionally specify whether an option prompt is presented by specifying the command line option `-isPrompting <true|false>`

    Throws:
      `ServiceException` - if unable to import the deployment.
    Since:
      9.2

  - ### importServiceDeployment

    public static void importServiceDeployment(com.sas.metadata.remote.MdStore mdStore, ServiceDeploymentImportFile serviceDeploymentImportFile, String repositoryName) throws ServiceException
    Imports a SAS Foundation Services deployment from a UTF-8 encoded SAS Foundation Services deployment XML file into the SAS Metadata Repository.
    Parameters:
      `mdStore` - Metadata store initialized with a factory which has a connection to the metadata server.
      `serviceDeploymentImportFile` - UTF-8 encoded SAS Foundation Services deployment file that is to be imported into the SAS Metadata Server.
      `repositoryName` - The name of the metadata repository into which the SAS Foundation Services deployment metadata is to be imported.
    Throws:
      `ServiceException` - if an exception is encountered.
    Since:
      9.2