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: * @(#)DeploymentServiceMBean.java
025: * Copyright 2004-2007 Sun Microsystems, Inc. All Rights Reserved.
026: *
027: * END_HEADER - DO NOT EDIT
028: */
029: package javax.jbi.management;
030:
031: import javax.management.ObjectName;
032:
033: /**
034: * The deployment service MBean allows administrative tools to manage
035: * service assembly deployments. The tasks supported are:
036: * <ul>
037: * <li>Deploying a service assembly.</li>
038: * <li>Undeploying a previously deployed service assembly.</li>
039: * <li>Querying deployed service assemblies:
040: * <ul>
041: * <li>For all components in the system.</li>
042: * <li>For a particular component.</li>
043: * </ul>
044: * </li>
045: * <li>Control the state of deployed service assemblies:
046: * <ul>
047: * <li>Start the service units that contained in the SA.</li>
048: * <li>Stop the service units that contained in the SA. </li>
049: * <li>Shut down the service units that contained in the SA.</li>
050: * </ul>
051: * </li>
052: * <li>Query the service units deployed to a particular component.</li>
053: * <li>Check if a service unit is deployed to a particular component.</li>
054: * <li>Query the deployment descriptor for a particular service assembly.</li>
055: * </ul>
056: *
057: * @author JSR208 Expert Group
058: */
059: public interface DeploymentServiceMBean {
060: /**
061: * Returns <code>true</code> if the the given component accepts the
062: * deployment of service units. This is used by admin tools to
063: * determine which components can be named in service assembly
064: * deployment descriptors.
065: *
066: * @param componentName name of the component; must be non-null and
067: * non-empty
068: * @return <code>true</code> if the named component accepts deployments;
069: * <code>false</code> if the named component does not accept
070: * deployments or it does not exist
071: *
072: */
073: boolean canDeployToComponent(String componentName);
074:
075: /**
076: * Deploys the given Service Assembly to the JBI environment.
077: * <p>
078: * Note that the implementation must not automatically start the service
079: * assembly after deployment; it must wait for the {@link #start(String)}
080: * method to be invoked by the administrative tool.
081: *
082: * @param serviceAssemblyZipUrl String containing the location URL of the
083: * Service Assembly ZIP file; must be non-null, non-empty, and a
084: * legal URL
085: * @return Result/Status of the current deployment; must conform to
086: * JBI management result/status XML schema; must be non-null and
087: * non-empty
088: * @exception Exception if complete deployment fails
089: */
090: public String deploy(String serviceAssemblyZipUrl) throws Exception;
091:
092: /**
093: * Undeploys the given Service Assembly from the JBI environment.
094: *
095: * @param serviceAssemblyName name of the Service Assembly that is to be
096: * undeployed; must be non-null and non-empty
097: * @return Result/Status of the current undeployment; must conform to
098: * JBI management result/status XML schema; must be non-null and
099: * non-empty
100: * @exception Exception if compelete undeployment fails
101: */
102: String undeploy(String serviceAssemblyName) throws Exception;
103:
104: /**
105: * Returns an array of service unit names that are currently deployed to
106: * the named component.
107: *
108: * @param componentName the name of the component to query; must be
109: * non-null and non-empty
110: * @return array of service unit names deployed in the named component;
111: * must be non-null; may be empty
112: * @exception Exception if a processing error occurs
113: */
114: String[] getDeployedServiceUnitList(String componentName)
115: throws Exception;
116:
117: /**
118: * Returns a list of Service Assemblies deployed to the JBI environment.
119: *
120: * @return list of Service Assembly names; must be non-null; may be
121: * empty
122: * @exception Exception if a processing error occurs
123: */
124: String[] getDeployedServiceAssemblies() throws Exception;
125:
126: /**
127: * Returns the deployment descriptor of the Service Assembly that was
128: * deployed to the JBI enviroment, serialized to a <code>String</code>.
129: *
130: * @param serviceAssemblyName name of the service assembly to be queried;
131: * must be non-null and non-empty
132: * @return descriptor of the Assembly Unit; must be non-null
133: * @exception Exception if a processing error occurs
134: */
135: String getServiceAssemblyDescriptor(String serviceAssemblyName)
136: throws Exception;
137:
138: /**
139: * Returns an array of Service Assembly names, where each assembly contains
140: * Service Units for the given component.
141: *
142: * @param componentName name of the component to query; must be non-null
143: * and non-empty
144: * @return array of of Service Assembly names, where each assembly contains
145: * a Service Unit for the named component; must be non-null; may
146: * be empty
147: * @exception Exception if a processing error occurs
148: */
149: String[] getDeployedServiceAssembliesForComponent(
150: String componentName) throws Exception;
151:
152: /**
153: * Returns an array of component names, where for each the given assembly
154: * contains a service unit for the component.
155: *
156: * @param serviceAssemblyName the service assembly to be queried; must be
157: * non-null and non-empty
158: * @return array of component names, where for each name the given assembly
159: * contains a service unit from the given service assembly; must
160: * be non-null; may be empty
161: * @exception Exception if a processing error occurs
162: */
163: String[] getComponentsForDeployedServiceAssembly(
164: String serviceAssemblyName) throws Exception;
165:
166: /**
167: * Queries if the named Service Unit is currently deployed to the named
168: * component.
169: *
170: * @param componentName name of the component to query; must be non-null
171: * and non-empty
172: * @param serviceUnitName name of the subject service unit; must be non-null
173: * and non-empty
174: * @return <code>true</code> if the named service unit is currently deployed
175: * to the named component
176: */
177: boolean isDeployedServiceUnit(String componentName,
178: String serviceUnitName) throws Exception;
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:
235: /*
236: * Enumeration of service assembly states
237: */
238:
239: /** The service assembly has been deployed, or shutdown */
240: final static String SHUTDOWN = "Shutdown";
241:
242: /** The service assembly is stopped. This means that the assembly's offered
243: * services can accept message exchanges, but it will not send any. */
244: final static String STOPPED = "Stopped";
245:
246: /** The service assembly is started. This means that the assembly's offered
247: * services can accept message exchanges, and it can send exchanges to
248: * consume services. */
249: final static String STARTED = "Started";
250: }
|