javax.jbi.component.ServiceUnitManager Maven / Gradle / Ivy
/*
* 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;
}