001: /*
002: * BEGIN_HEADER - DO NOT EDIT
003: *
004: * The contents of this file are subject to the terms
005: * of the Common Development and Distribution License
006: * (the "License"). You may not use this file except
007: * in compliance with the License.
008: *
009: * You can obtain a copy of the license at
010: * https://open-esb.dev.java.net/public/CDDLv1.0.html.
011: * See the License for the specific language governing
012: * permissions and limitations under the License.
013: *
014: * When distributing Covered Code, include this CDDL
015: * HEADER in each file and include the License file at
016: * https://open-esb.dev.java.net/public/CDDLv1.0.html.
017: * If applicable add the following below this CDDL HEADER,
018: * with the fields enclosed by brackets "[]" replaced with
019: * your own identifying information: Portions Copyright
020: * [year] [name of copyright owner]
021: */
022:
023: /*
024: * @(#)ServiceUnitManager.java
025: * Copyright 2004-2007 Sun Microsystems, Inc. All Rights Reserved.
026: *
027: * END_HEADER - DO NOT EDIT
028: */
029: package javax.jbi.component;
030:
031: import javax.jbi.management.DeploymentException;
032:
033: /**
034: * This interface defines component-supplied methods for managing service
035: * unit deployments, and is implemented by the component. The JBI implementation
036: * queries the component for the implementation of this interface using the
037: * {@link Component#getServiceUnitManager()} method.
038: *
039: * @author JSR208 Expert Group
040: */
041: public interface ServiceUnitManager {
042: /**
043: * Deploy a Service Unit to the component. This is called by the JBI
044: * implementation in order to deploy the given artifact to the implementing
045: * component.
046: * <p>
047: * Upon successful deployment, a non-empty result string must be returned,
048: * that starts with the JBI-defined component-task-result element.
049: * For example:
050: * <pre>
051: * <component-task-result>
052: * <component-name>BC1</component-name>
053: * <component-task-result-details
054: * xmlns="http://java.sun.com/xml/ns/jbi/management-message">
055: * <task-result-details>
056: * <task-id>deploy</task-id>
057: * <task-result>SUCCESS</task-result>
058: * </task-result-details>
059: * </component-task-result-details>
060: * </component-task-result>
061: * </pre>
062: * A failed deployment of the service unit must be reported using the
063: * <code>component-task-result</code> element as well; the
064: * <code>task-result</code> must be set to FAILED.
065: *
066: * @param serviceUnitName name of the service unit being deployed; must be
067: * non-null and non-empty and unique among service units already
068: * deployed to the component.
069: * @param serviceUnitRootPath path of the service unit artifact root, in
070: * platform specific format; must be non-null and non-empty.
071: * @return a deployment status message, which is an XML string that conforms
072: * to the schema given in the <i>MBean Status and Result Strings</i>
073: * section of the <i><b>Management</b></i> chapter of the JBI
074: * specification; must be non-null and non-empty.
075: * @exception DeploymentException if the deployment operation is
076: * unsuccessful.
077: */
078: String deploy(String serviceUnitName, String serviceUnitRootPath)
079: throws DeploymentException;
080:
081: /**
082: * Initialize the given deployed service unit. This is the first phase of
083: * a two-phase start, where the component must prepare to receive service
084: * requests related to the deployment (if any).
085: * <p>
086: * The serviceUnitRootPath parameter is provided to facilitate restart of
087: * the component. This allows simple components to rely entirely on JBI's
088: * ability to persist deployment information, avoiding the need for the
089: * component to provide its own persistence mechanism.
090: *
091: * @param serviceUnitName name of the service unit being initialized; must
092: * be non-null, non-empty, and match the name of a previously
093: * deployed (but not yet undeployed) service unit.
094: * @param serviceUnitRootPath path of the service unit artifact root, in
095: * platform specific format; must be non-null and non-empty.
096: * @exception DeploymentException if the service unit is not deployed, or
097: * if it is in an incorrect state.
098: */
099: void init(String serviceUnitName, String serviceUnitRootPath)
100: throws DeploymentException;
101:
102: /**
103: * Start the deployed service unit. This is the second phase of a two-phase
104: * start, where the component can now initiate service requests related to
105: * the deployment.
106: *
107: * @param serviceUnitName the name of the service unit being started; must
108: * be non-null, non-empty, and match the name of a previously
109: * deployed (but not yet undeployed) service unit.
110: * @exception DeploymentException if the service unit is not deployed, or
111: * if it is in an incorrect state.
112: */
113: void start(String serviceUnitName) throws DeploymentException;
114:
115: /**
116: * Stop the deployed service unit. This causes the component to cease
117: * generating service requests related to the given service unit. This
118: * returns the service unit to a state equivalent to after
119: * {@link #init(String, String)} was called.
120: *
121: * @param serviceUnitName name of the service unit being stopped; must
122: * be non-null, non-empty, and match the name of a previously
123: * deployed (but not yet undeployed) service unit.
124: * @exception DeploymentException if the service unit is not deployed, or
125: * if it is in an incorrect state.
126: */
127: void stop(String serviceUnitName) throws DeploymentException;
128:
129: /**
130: * Shut down the deployment. This causes the deployment to return to the
131: * to the state it was in after {@link #deploy(String, String)}, and before
132: * {@link #init(String, String)}.
133: *
134: * @param serviceUnitName name of the service unit being shut down; must
135: * be non-null, non-empty, and match the name of a previously
136: * deployed (but not yet undeployed) service unit.
137: * @exception DeploymentException if the service unit is not deployed, or
138: * if it is in an incorrect state.
139: */
140: void shutDown(String serviceUnitName) throws DeploymentException;
141:
142: /**
143: * Undeploy a service unit from the component. The service unit must be
144: * shut down to undeploy it.
145: *
146: * @param serviceUnitName name of the service unit being undeployed; must
147: * be non-null, non-empty, and match the name of a previously
148: * deployed (but not yet undeployed) service unit.
149: * @param serviceUnitRootPath path of the service unit artifact root, in
150: * platform specific format; must be non-null and non-empty.
151: * @return deployment status message, which is an XML string that conforms
152: * to the <code>component-task-result</code> type from
153: * the schema given in the <i>MBean Status and Result Strings</i>
154: * section of the <i><b>Management</b></i> chapter of the JBI
155: * specification; must be non-null and non-empty.
156: * @exception DeploymentException if undeployment operation is unsuccessful,
157: * or if the service unit is in an incorrect state.
158: */
159: String undeploy(String serviceUnitName, String serviceUnitRootPath)
160: throws DeploymentException;
161: }
|