javax.jbi.component.ServiceUnitManager Maven / Gradle / Ivy
Show all versions of petals-jbi Show documentation
/**
* @(#) ServiceUnitManager.java
*
* PETALS - PETALS Services Platform.
* Copyright (c) 2005 Fossil E-Commerce, http://www.fossilec.com/
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*
* -------------------------------------------------------------------------
* $Id: ServiceUnitManager.java 69 2006-01-17 16:00:26Z rmarins $
* -------------------------------------------------------------------------
*/
//
// This source code implements specifications defined by the Java
// Community Process. In order to remain compliant with the specification
// DO NOT add / change / or delete method signatures!
//
package javax.jbi.component;
/**
* 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 object using the
* {@link Component#getServiceUnitManager()} method.
*
* @author JSR208 Expert Group
*/
public interface ServiceUnitManager {
/**
* 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.
*
* @param 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.
* @param serviceUnitRootPath
* path of the service unit artifact root, in platform-specific
* format; must be non-null and non-empty.
* @return 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 javax.jbi.management.DeploymentException
* if the deployment operation is unsuccessful.
*/
public java.lang.String deploy(java.lang.String serviceUnitName,
java.lang.String serviceUnitRootPath)
throws javax.jbi.management.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 simply components to rely entirely on JBI's
* ability to persist deployment information, avoiding the need to build
* persistance into the component.
*
* @param 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.
* @param serviceUnitRootPath
* path of the service unit artifact root, in platform specific
* format; must be non-null and non-empty.
* @throws javax.jbi.management.DeploymentException
* if the service unit is not deployed, or if it is in an
* incorrect state.
*/
public void init(java.lang.String serviceUnitName,
java.lang.String serviceUnitRootPath)
throws javax.jbi.management.DeploymentException;
/**
* Shut down the deployed service unit. This causes the component to return
* to the state it was in after
* {@link ServiceUnitManager#deploy(String, String)}, and before
* {@link ServiceUnitManager#init(String, String)}.
*
* @param 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 javax.jbi.management.DeploymentException
* if the service unit is not deployed, or if it is in an
* incorrect state.
*/
public void shutDown(java.lang.String serviceUnitName)
throws javax.jbi.management.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.
*
* @param serviceUnitName
* 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 javax.jbi.management.DeploymentException
* if the service unit is not deployed, or if it is in an
* incorrect state.
*/
public void start(java.lang.String serviceUnitName)
throws javax.jbi.management.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
* {@link ServiceUnitManager#init(String, String)} was called.
*
* @param 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 javax.jbi.management.DeploymentException
* if the service unit is not deployed, or if it is in an
* incorrect state.
*/
public void stop(java.lang.String serviceUnitName)
throws javax.jbi.management.DeploymentException;
/**
* Undeploy a Service Unit from the component. The service unit must be
* shutdown to undeploy it.
*
* @param 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
* @param serviceUnitRootPath
* path of the service unit artifact root, in platform-specific
* format; must be non-null and non-empty.
* @return deployment status message, which is an XML string that conforms
* to the component-task-result-details 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 javax.jbi.management.DeploymentException
* if undeployment operation is unsuccessful.
*/
public java.lang.String undeploy(java.lang.String serviceUnitName,
java.lang.String serviceUnitRootPath)
throws javax.jbi.management.DeploymentException;
}