## javax.jbi.component
Interface ServiceUnitManager

    public interface ServiceUnitManager

This interface defines component-supplied methods for managing service unit deployments, and is implemented by the component. The JBI implementation queries the component for the implementation of this interface using the `Component.getServiceUnitManager()` method.

Author:
  JSR208 Expert Group

Method Summary
`java.lang.String` `deploy(java.lang.String serviceUnitName, java.lang.String serviceUnitRootPath)` Deploy a Service Unit to the component.
`void` `init(java.lang.String serviceUnitName, java.lang.String serviceUnitRootPath)` Initialize the given deployed service unit.
`void` `shutDown(java.lang.String serviceUnitName)` Shut down the deployment.
`void` `start(java.lang.String serviceUnitName)` Start the deployed service unit.
`void` `stop(java.lang.String serviceUnitName)` Stop the deployed service unit.
`java.lang.String` `undeploy(java.lang.String serviceUnitName, java.lang.String serviceUnitRootPath)` Undeploy a service unit from the component.

Method Detail

### deploy

    java.lang.String deploy(java.lang.String serviceUnitName,
                            java.lang.String serviceUnitRootPath)
                            throws DeploymentException

  Deploy a Service Unit to the component. This is called by the JBI implementation in order to deploy the given artifact to the implementing component.

  Upon successful deployment, a non-empty result string must be returned, that starts with the JBI-defined component-task-result element. For example:

       <component-task-result>
         <component-name>BC1</component-name>
         <component-task-result-details
           xmlns="http://java.sun.com/xml/ns/jbi/management-message">
             <task-result-details>
                 <task-id>deploy</task-id>
                 <task-result>SUCCESS</task-result>
             </task-result-details>
         </component-task-result-details>
       </component-task-result>

  A failed deployment of the service unit must be reported using the `component-task-result` element as well; the `task-result` must be set to FAILED.

  Parameters:
    `serviceUnitName` - name of the service unit being deployed; must be non-null and non-empty and unique among service units already deployed to the component.
    `serviceUnitRootPath` - path of the service unit artifact root, in platform specific format; must be non-null and non-empty.
  Returns:
    a deployment status message, which is an XML string that conforms to the schema given in the MBean Status and Result Strings section of the Management chapter of the JBI specification; must be non-null and non-empty.
  Throws:
    `DeploymentException` - if the deployment operation is unsuccessful.

### init

    void init(java.lang.String serviceUnitName,
              java.lang.String serviceUnitRootPath)
              throws DeploymentException

  Initialize the given deployed service unit. This is the first phase of a two-phase start, where the component must prepare to receive service requests related to the deployment (if any).

  The serviceUnitRootPath parameter is provided to facilitate restart of the component. This allows simple components to rely entirely on JBI's ability to persist deployment information, avoiding the need for the component to provide its own persistence mechanism.

  Parameters:
    `serviceUnitName` - name of the service unit being initialized; must be non-null, non-empty, and match the name of a previously deployed (but not yet undeployed) service unit.
    `serviceUnitRootPath` - path of the service unit artifact root, in platform specific format; must be non-null and non-empty.
  Throws:
    `DeploymentException` - if the service unit is not deployed, or if it is in an incorrect state.

### start

    void start(java.lang.String serviceUnitName)
               throws DeploymentException

  Start the deployed service unit. This is the second phase of a two-phase start, where the component can now initiate service requests related to the deployment.

  Parameters:
    `serviceUnitName` - the name of the service unit being started; must be non-null, non-empty, and match the name of a previously deployed (but not yet undeployed) service unit.
  Throws:
    `DeploymentException` - if the service unit is not deployed, or if it is in an incorrect state.

### stop

    void stop(java.lang.String serviceUnitName)
              throws DeploymentException

  Stop the deployed service unit. This causes the component to cease generating service requests related to the given service unit. This returns the service unit to a state equivalent to after `init(String, String)` was called.

  Parameters:
    `serviceUnitName` - name of the service unit being stopped; must be non-null, non-empty, and match the name of a previously deployed (but not yet undeployed) service unit.
  Throws:
    `DeploymentException` - if the service unit is not deployed, or if it is in an incorrect state.

### shutDown

    void shutDown(java.lang.String serviceUnitName)
                  throws DeploymentException

  Shut down the deployment. This causes the deployment to return to the to the state it was in after `deploy(String, String)`, and before `init(String, String)`.

  Parameters:
    `serviceUnitName` - name of the service unit being shut down; must be non-null, non-empty, and match the name of a previously deployed (but not yet undeployed) service unit.
  Throws:
    `DeploymentException` - if the service unit is not deployed, or if it is in an incorrect state.

### undeploy

    java.lang.String undeploy(java.lang.String serviceUnitName,
                              java.lang.String serviceUnitRootPath)
                              throws DeploymentException

  Undeploy a service unit from the component. The service unit must be shut down to undeploy it.

  Parameters:
    `serviceUnitName` - name of the service unit being undeployed; must be non-null, non-empty, and match the name of a previously deployed (but not yet undeployed) service unit.
    `serviceUnitRootPath` - path of the service unit artifact root, in platform specific format; must be non-null and non-empty.
  Returns:
    deployment status message, which is an XML string that conforms to the `component-task-result` type from the schema given in the MBean Status and Result Strings section of the Management chapter of the JBI specification; must be non-null and non-empty.
  Throws:
    `DeploymentException` - if undeployment operation is unsuccessful, or if the service unit is in an incorrect state.

${build-info}

${copyright}