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.management;
018    
019    /**
020     * The deployment service MBean allows administrative tools to manage
021     * service assembly deployments. The tasks supported are:
022     * <ul>
023     *   <li>Deploying a service assembly.</li>
024     *   <li>Undeploying a previously deployed service assembly.</li>
025     *   <li>Querying deployed service assemblies:
026     *     <ul>
027     *       <li>For all components in the system.</li>
028     *       <li>For a particular component.</li>
029     *     </ul>
030     *   </li>
031     *   <li>Control the state of deployed service assemblies:
032     *     <ul>
033     *       <li>Start the service units that contained in the SA.</li>
034     *       <li>Stop the service units that contained in the SA. </li>
035     *       <li>Shut down the service units that contained in the SA.</li>
036     *     </ul>
037     *   </li>
038     *   <li>Query the service units deployed to a particular component.</li>
039     *   <li>Check if a service unit is deployed to a particular component.</li>
040     *   <li>Query the deployment descriptor for a particular service assembly.</li>
041     * </ul>
042     *
043     * @author JSR208 Expert Group
044     */
045    public interface DeploymentServiceMBean {
046    
047        /**
048         * The service assembly is started. This means that the assembly's offered
049         * services can accept message exchanges, and it can send exchanges to
050         * consume services.
051         */
052        String STARTED = "Started";
053    
054        /**
055         * The service assembly has been deployed, or shutdown
056         */
057         String SHUTDOWN = "Shutdown";
058    
059        /**
060         * The service assembly is stopped. This means that the assembly's offered
061         * services can accept message exchanges, but it will not send any.
062         */
063        String STOPPED = "Stopped";
064    
065        /**
066         * Deploys the given Service Assembly to the JBI environment.
067         * <p>
068         * Note that the implementation must not automatically start the service
069         * assembly after deployment; it must wait for the {@link #start(String)}
070         * method to be invoked by the administrative tool.
071         *
072         * @param saZipURL String containing the location URL of the
073         *        Service Assembly ZIP file; must be non-null, non-empty, and a
074         *        legal URL
075         * @return Result/Status of the current deployment; must conform to
076         *         JBI management result/status XML schema; must be non-null and
077         *         non-empty
078         * @exception Exception if complete deployment fails
079         */
080        String deploy(String saZipURL) throws Exception;
081    
082        /**
083         * Undeploys the given Service Assembly from the JBI environment.
084         *
085         * @param saName name of the Service Assembly that is to be 
086         *        undeployed; must be non-null and non-empty
087         * @return Result/Status of the current undeployment; must conform to
088         *         JBI management result/status XML schema; must be non-null and
089         *         non-empty
090         * @exception Exception if compelete undeployment fails
091         */
092        String undeploy(String saName) throws Exception;
093    
094        /**
095         * Returns an array of service unit names that are currently deployed to
096         * the named component.
097         *
098         * @param componentName the name of the component to query; must be
099         *        non-null and non-empty
100         * @return array of service unit names deployed in the named component;
101         *         must be non-null; may be empty
102         * @exception Exception if a processing error occurs
103         */
104        String[] getDeployedServiceUnitList(String componentName) throws Exception;
105    
106        /**
107         * Returns a list of Service Assemblies deployed to the JBI environment.
108         *
109         * @return list of Service Assembly names; must be non-null; may be
110         *         empty
111         * @exception Exception if a processing error occurs
112         */
113        String[] getDeployedServiceAssemblies() throws Exception;
114    
115        /**
116         * Returns the deployment descriptor of the Service Assembly that was
117         * deployed to the JBI enviroment, serialized to a <code>String</code>.
118         *
119         * @param saName name of the service assembly to be queried;
120         *        must be non-null and non-empty
121         * @return descriptor of the Assembly Unit; must be non-null
122         * @exception Exception if a processing error occurs
123         */
124        String getServiceAssemblyDescriptor(String saName) throws Exception;
125    
126        /**
127         * Returns an array of Service Assembly names, where each assembly contains
128         * Service Units for the given component.
129         *
130         * @param componentName name of the component to query; must be non-null
131         *        and non-empty
132         * @return array of of Service Assembly names, where each assembly contains
133         *         a Service Unit for the named component; must be non-null; may
134         *         be empty
135         * @exception Exception if a processing error occurs
136         */
137        String[] getDeployedServiceAssembliesForComponent(String componentName) throws Exception;
138    
139        /**
140         * Returns an array of component names, where for each the given assembly
141         * contains a service unit for the component.
142         *
143         * @param saName the service assembly to be queried; must be
144         *        non-null and non-empty
145         * @return array of component names, where for each name the given assembly
146         *         contains a service unit from the given service assembly; must
147         *         be non-null; may be empty
148         * @exception Exception if a processing error occurs
149         */
150        String[] getComponentsForDeployedServiceAssembly(String saName) throws Exception;
151    
152        /**
153         * Queries if the named Service Unit is currently deployed to the named
154         * component.
155         *
156         * @param componentName name of the component to query; must be non-null
157         *        and non-empty
158         * @param suName name of the subject service unit; must be non-null
159         *        and non-empty
160         * @return <code>true</code> if the named service unit is currently deployed
161         *         to the named component
162         */
163        boolean isDeployedServiceUnit(String componentName, String suName) throws Exception;
164    
165        /**
166         * Returns <code>true</code> if the the given component accepts the
167         * deployment of service units. This is used by admin tools to
168         * determine which components can be named in service assembly
169         * deployment descriptors.
170         *
171         * @param componentName name of the component; must be non-null and
172         *        non-empty
173         * @return <code>true</code> if the named component accepts deployments;
174         *         <code>false</code> if the named component does not accept
175         *         deployments or it does not exist
176         *
177         */
178        boolean canDeployToComponent(String componentName);
179    
180        /**
181         * Start the service assembly. This puts the assembly into the {@link
182         * #STARTED} state.
183         *
184         * @param serviceAssemblyName name of the assembly to be started; must be
185         *        non-null and non-empty
186         * @return result / status string giving the results of starting (and
187         *         possibly initializing) each service unit in the assembly; must
188         *         be non-null and non-empty
189         * @exception Exception if there is no such assembly
190         * @exception Exception if the assembly fails to start
191         *
192         */
193        String start(String serviceAssemblyName) throws Exception;
194    
195        /**
196         * Stop the service assembly. This puts the assembly into the {@link
197         * #STOPPED} state.
198         *
199         * @param serviceAssemblyName name of the assembly to be stopped; must be
200         *        non-null and non-empty
201         * @return result / status string giving the results of stopping each
202         *         service unit in the assembly; must be non-null and non-empty
203         * @exception Exception if there is no such assembly
204         * @exception Exception if the assembly fails to stop
205         */
206        String stop(String serviceAssemblyName) throws Exception;
207    
208        /**
209         * Shut down the service assembly. This puts the assembly back into the
210         * {@link #SHUTDOWN} state.
211         *
212         * @param serviceAssemblyName name of the assembly to be shut down; must be
213         *        non-null and non-empty
214         * @return result / status string giving the results of shutting down
215         *         each service unit in the assembly; must be non-null and non-empty
216         * @exception Exception if there is no such assembly
217         * @exception Exception if the assembly fails to shut down
218         */
219        String shutDown(String serviceAssemblyName) throws Exception;
220    
221        /**
222         * Get the running state of a service assembly. The possible result values
223         * of this query are enumerated by the following set of constants:
224         * {@link #SHUTDOWN}, {@link #STOPPED}, {@link #STARTED}.
225         *
226         * @param serviceAssemblyName name of the assembly to query; must be
227         *        non-null and non-empty
228         * @return the state of the service assembly, as a string value; must be one
229         *         of the enumerated string values provided by this interface:
230         *         {@link #SHUTDOWN}, {@link #STOPPED}, or {@link #STARTED}
231         * @exception Exception if there is no such assembly
232         */
233        String getState(String serviceAssemblyName) throws Exception;
234    }