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 }