| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| package javax.jbi.management; |
| |
| /** |
| * The deployment service MBean allows administrative tools to manage |
| * service assembly deployments. The tasks supported are: |
| * <ul> |
| * <li>Deploying a service assembly.</li> |
| * <li>Undeploying a previously deployed service assembly.</li> |
| * <li>Querying deployed service assemblies: |
| * <ul> |
| * <li>For all components in the system.</li> |
| * <li>For a particular component.</li> |
| * </ul> |
| * </li> |
| * <li>Control the state of deployed service assemblies: |
| * <ul> |
| * <li>Start the service units that contained in the SA.</li> |
| * <li>Stop the service units that contained in the SA. </li> |
| * <li>Shut down the service units that contained in the SA.</li> |
| * </ul> |
| * </li> |
| * <li>Query the service units deployed to a particular component.</li> |
| * <li>Check if a service unit is deployed to a particular component.</li> |
| * <li>Query the deployment descriptor for a particular service assembly.</li> |
| * </ul> |
| * |
| * @author JSR208 Expert Group |
| */ |
| public interface DeploymentServiceMBean { |
| |
| /** |
| * The service assembly is started. This means that the assembly's offered |
| * services can accept message exchanges, and it can send exchanges to |
| * consume services. |
| */ |
| String STARTED = "Started"; |
| |
| /** |
| * The service assembly has been deployed, or shutdown |
| */ |
| String SHUTDOWN = "Shutdown"; |
| |
| /** |
| * The service assembly is stopped. This means that the assembly's offered |
| * services can accept message exchanges, but it will not send any. |
| */ |
| String STOPPED = "Stopped"; |
| |
| /** |
| * Deploys the given Service Assembly to the JBI environment. |
| * <p> |
| * Note that the implementation must not automatically start the service |
| * assembly after deployment; it must wait for the {@link #start(String)} |
| * method to be invoked by the administrative tool. |
| * |
| * @param saZipURL String containing the location URL of the |
| * Service Assembly ZIP file; must be non-null, non-empty, and a |
| * legal URL |
| * @return Result/Status of the current deployment; must conform to |
| * JBI management result/status XML schema; must be non-null and |
| * non-empty |
| * @exception Exception if complete deployment fails |
| */ |
| String deploy(String saZipURL) throws Exception; |
| |
| /** |
| * Undeploys the given Service Assembly from the JBI environment. |
| * |
| * @param saName name of the Service Assembly that is to be |
| * undeployed; must be non-null and non-empty |
| * @return Result/Status of the current undeployment; must conform to |
| * JBI management result/status XML schema; must be non-null and |
| * non-empty |
| * @exception Exception if compelete undeployment fails |
| */ |
| String undeploy(String saName) throws Exception; |
| |
| /** |
| * Returns an array of service unit names that are currently deployed to |
| * the named component. |
| * |
| * @param componentName the name of the component to query; must be |
| * non-null and non-empty |
| * @return array of service unit names deployed in the named component; |
| * must be non-null; may be empty |
| * @exception Exception if a processing error occurs |
| */ |
| String[] getDeployedServiceUnitList(String componentName) throws Exception; |
| |
| /** |
| * Returns a list of Service Assemblies deployed to the JBI environment. |
| * |
| * @return list of Service Assembly names; must be non-null; may be |
| * empty |
| * @exception Exception if a processing error occurs |
| */ |
| String[] getDeployedServiceAssemblies() throws Exception; |
| |
| /** |
| * Returns the deployment descriptor of the Service Assembly that was |
| * deployed to the JBI enviroment, serialized to a <code>String</code>. |
| * |
| * @param saName name of the service assembly to be queried; |
| * must be non-null and non-empty |
| * @return descriptor of the Assembly Unit; must be non-null |
| * @exception Exception if a processing error occurs |
| */ |
| String getServiceAssemblyDescriptor(String saName) throws Exception; |
| |
| /** |
| * Returns an array of Service Assembly names, where each assembly contains |
| * Service Units for the given component. |
| * |
| * @param componentName name of the component to query; must be non-null |
| * and non-empty |
| * @return array of of Service Assembly names, where each assembly contains |
| * a Service Unit for the named component; must be non-null; may |
| * be empty |
| * @exception Exception if a processing error occurs |
| */ |
| String[] getDeployedServiceAssembliesForComponent(String componentName) throws Exception; |
| |
| /** |
| * Returns an array of component names, where for each the given assembly |
| * contains a service unit for the component. |
| * |
| * @param saName the service assembly to be queried; must be |
| * non-null and non-empty |
| * @return array of component names, where for each name the given assembly |
| * contains a service unit from the given service assembly; must |
| * be non-null; may be empty |
| * @exception Exception if a processing error occurs |
| */ |
| String[] getComponentsForDeployedServiceAssembly(String saName) throws Exception; |
| |
| /** |
| * Queries if the named Service Unit is currently deployed to the named |
| * component. |
| * |
| * @param componentName name of the component to query; must be non-null |
| * and non-empty |
| * @param suName name of the subject service unit; must be non-null |
| * and non-empty |
| * @return <code>true</code> if the named service unit is currently deployed |
| * to the named component |
| */ |
| boolean isDeployedServiceUnit(String componentName, String suName) throws Exception; |
| |
| /** |
| * Returns <code>true</code> if the the given component accepts the |
| * deployment of service units. This is used by admin tools to |
| * determine which components can be named in service assembly |
| * deployment descriptors. |
| * |
| * @param componentName name of the component; must be non-null and |
| * non-empty |
| * @return <code>true</code> if the named component accepts deployments; |
| * <code>false</code> if the named component does not accept |
| * deployments or it does not exist |
| * |
| */ |
| boolean canDeployToComponent(String componentName); |
| |
| /** |
| * Start the service assembly. This puts the assembly into the {@link |
| * #STARTED} state. |
| * |
| * @param serviceAssemblyName name of the assembly to be started; must be |
| * non-null and non-empty |
| * @return result / status string giving the results of starting (and |
| * possibly initializing) each service unit in the assembly; must |
| * be non-null and non-empty |
| * @exception Exception if there is no such assembly |
| * @exception Exception if the assembly fails to start |
| * |
| */ |
| String start(String serviceAssemblyName) throws Exception; |
| |
| /** |
| * Stop the service assembly. This puts the assembly into the {@link |
| * #STOPPED} state. |
| * |
| * @param serviceAssemblyName name of the assembly to be stopped; must be |
| * non-null and non-empty |
| * @return result / status string giving the results of stopping each |
| * service unit in the assembly; must be non-null and non-empty |
| * @exception Exception if there is no such assembly |
| * @exception Exception if the assembly fails to stop |
| */ |
| String stop(String serviceAssemblyName) throws Exception; |
| |
| /** |
| * Shut down the service assembly. This puts the assembly back into the |
| * {@link #SHUTDOWN} state. |
| * |
| * @param serviceAssemblyName name of the assembly to be shut down; must be |
| * non-null and non-empty |
| * @return result / status string giving the results of shutting down |
| * each service unit in the assembly; must be non-null and non-empty |
| * @exception Exception if there is no such assembly |
| * @exception Exception if the assembly fails to shut down |
| */ |
| String shutDown(String serviceAssemblyName) throws Exception; |
| |
| /** |
| * Get the running state of a service assembly. The possible result values |
| * of this query are enumerated by the following set of constants: |
| * {@link #SHUTDOWN}, {@link #STOPPED}, {@link #STARTED}. |
| * |
| * @param serviceAssemblyName name of the assembly to query; must be |
| * non-null and non-empty |
| * @return the state of the service assembly, as a string value; must be one |
| * of the enumerated string values provided by this interface: |
| * {@link #SHUTDOWN}, {@link #STOPPED}, or {@link #STARTED} |
| * @exception Exception if there is no such assembly |
| */ |
| String getState(String serviceAssemblyName) throws Exception; |
| } |