/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package javax.jbi.component; import javax.jbi.management.DeploymentException; /** * 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 {@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 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.
* @exception DeploymentException if the deployment operation is
* unsuccessful.
*/
String deploy(String serviceUnitName, 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.
*
* @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.
* @exception DeploymentException if the service unit is not deployed, or
* if it is in an incorrect state.
*/
void init(String serviceUnitName, String serviceUnitRootPath) 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.
*
* @param 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.
* @exception DeploymentException if the service unit is not deployed, or
* if it is in an incorrect state.
*/
void start(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
* {@link #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.
* @exception DeploymentException if the service unit is not deployed, or
* if it is in an incorrect state.
*/
void stop(String serviceUnitName) throws DeploymentException;
/**
* Shut down the deployment. This causes the deployment to return to the
* to the state it was in after {@link #deploy(String, String)}, and before
* {@link #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.
* @exception DeploymentException if the service unit is not deployed, or
* if it is in an incorrect state.
*/
void shutDown(String serviceUnitName) throws DeploymentException;
/**
* Undeploy a service unit from the component. The service unit must be
* shut down 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
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.
* @exception DeploymentException if undeployment operation is unsuccessful,
* or if the service unit is in an incorrect state.
*/
String undeploy(String serviceUnitName, String serviceUnitRootPath) throws DeploymentException;
}