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         * &lt;component-task-result&gt;
040         *   &lt;component-name&gt;BC1&lt;/component-name&gt;
041         *   &lt;component-task-result-details
042         *     xmlns="http://java.sun.com/xml/ns/jbi/management-message"&gt;
043         *       &lt;task-result-details&gt;
044         *           &lt;task-id>deploy&lt;/task-id&gt;
045         *           &lt;task-result>SUCCESS&lt;/task-result&gt;
046         *       &lt;/task-result-details&gt;
047         *   &lt;/component-task-result-details&gt;
048         * &lt;/component-task-result&gt;
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    }