001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017 package javax.jbi.component;
018
019 import javax.jbi.management.DeploymentException;
020
021 /**
022 * This interface defines component-supplied methods for managing service
023 * unit deployments, and is implemented by the component. The JBI
024 * implementation queries the component for the implementation of this
025 * interface using the {@link Component#getServiceUnitManager()} method.
026 *
027 * @author JSR208 Expert Group
028 */
029 public interface ServiceUnitManager {
030
031 /**
032 * Deploy a Service Unit to the component. This is called by the JBI
033 * implementation in order to deploy the given artifact to the implementing
034 * component.
035 *
036 * Upon successful deployment, a non-empty result string must be returned,
037 * that starts with the JBI-defined component-task-result element. For example:
038 * <pre>
039 * <component-task-result>
040 * <component-name>BC1</component-name>
041 * <component-task-result-details
042 * xmlns="http://java.sun.com/xml/ns/jbi/management-message">
043 * <task-result-details>
044 * <task-id>deploy</task-id>
045 * <task-result>SUCCESS</task-result>
046 * </task-result-details>
047 * </component-task-result-details>
048 * </component-task-result>
049 * </pre>
050 * A failed deployment of the service unit must be reported using the
051 * <code>component-task-result</code> element as well; the
052 * <code>task-result</code> must be set to FAILED.
053 *
054 * @param serviceUnitName name of the service unit being deployed; must be
055 * non-null and non-empty and unique among service units already
056 * deployed to the component.
057 * @param serviceUnitRootPath path of the service unit artifact root, in
058 * platform specific format; must be non-null and non-empty.
059 * @return a deployment status message, which is an XML string that conforms
060 * to the schema given in the <i>MBean Status and Result Strings</i>
061 * section of the <i><b>Management</b></i> chapter of the JBI
062 * specification; must be non-null and non-empty.
063 * @exception DeploymentException if the deployment operation is
064 * unsuccessful.
065 */
066 String deploy(String serviceUnitName, String serviceUnitRootPath) throws DeploymentException;
067
068 /**
069 * Initialize the given deployed service unit. This is the first phase of
070 * a two-phase start, where the component must prepare to receive service
071 * requests related to the deployment (if any).
072 * <p>
073 * The serviceUnitRootPath parameter is provided to facilitate restart of
074 * the component. This allows simple components to rely entirely on JBI's
075 * ability to persist deployment information, avoiding the need for the
076 * component to provide its own persistence mechanism.
077 *
078 * @param serviceUnitName name of the service unit being initialized; must
079 * be non-null, non-empty, and match the name of a previously
080 * deployed (but not yet undeployed) service unit.
081 * @param serviceUnitRootPath path of the service unit artifact root, in
082 * platform specific format; must be non-null and non-empty.
083 * @exception DeploymentException if the service unit is not deployed, or
084 * if it is in an incorrect state.
085 */
086 void init(String serviceUnitName, String serviceUnitRootPath) throws DeploymentException;
087
088 /**
089 * Start the deployed service unit. This is the second phase of a two-phase
090 * start, where the component can now initiate service requests related to
091 * the deployment.
092 *
093 * @param serviceUnitName the name of the service unit being started; must
094 * be non-null, non-empty, and match the name of a previously
095 * deployed (but not yet undeployed) service unit.
096 * @exception DeploymentException if the service unit is not deployed, or
097 * if it is in an incorrect state.
098 */
099 void start(String serviceUnitName) throws DeploymentException;
100
101 /**
102 * Stop the deployed service unit. This causes the component to cease
103 * generating service requests related to the given service unit. This
104 * returns the service unit to a state equivalent to after
105 * {@link #init(String, String)} was called.
106 *
107 * @param serviceUnitName name of the service unit being stopped; 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 stop(String serviceUnitName) throws DeploymentException;
114
115 /**
116 * Shut down the deployment. This causes the deployment to return to the
117 * to the state it was in after {@link #deploy(String, String)}, and before
118 * {@link #init(String, String)}.
119 *
120 * @param serviceUnitName name of the service unit being shut down; must
121 * be non-null, non-empty, and match the name of a previously
122 * deployed (but not yet undeployed) service unit.
123 * @exception DeploymentException if the service unit is not deployed, or
124 * if it is in an incorrect state.
125 */
126 void shutDown(String serviceUnitName) throws DeploymentException;
127
128 /**
129 * Undeploy a service unit from the component. The service unit must be
130 * shut down to undeploy it.
131 *
132 * @param serviceUnitName name of the service unit being undeployed; must
133 * be non-null, non-empty, and match the name of a previously
134 * deployed (but not yet undeployed) service unit.
135 * @param serviceUnitRootPath path of the service unit artifact root, in
136 * platform specific format; must be non-null and non-empty.
137 * @return deployment status message, which is an XML string that conforms
138 * to the <code>component-task-result</code> type from
139 * the schema given in the <i>MBean Status and Result Strings</i>
140 * section of the <i><b>Management</b></i> chapter of the JBI
141 * specification; must be non-null and non-empty.
142 * @exception DeploymentException if undeployment operation is unsuccessful,
143 * or if the service unit is in an incorrect state.
144 */
145 String undeploy(String serviceUnitName, String serviceUnitRootPath) throws DeploymentException;
146 }