javax.jbi.management.DeploymentServiceMBean Maven / Gradle / Ivy
/*
* 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:
*
* - Deploying a service assembly.
* - Undeploying a previously deployed service assembly.
* - Querying deployed service assemblies:
*
* - For all components in the system.
* - For a particular component.
*
*
* - Control the state of deployed service assemblies:
*
* - Start the service units that contained in the SA.
* - Stop the service units that contained in the SA.
* - Shut down the service units that contained in the SA.
*
*
* - Query the service units deployed to a particular component.
* - Check if a service unit is deployed to a particular component.
* - Query the deployment descriptor for a particular service assembly.
*
*
* @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.
*
* 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 String.
*
* @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 true if the named service unit is currently deployed
* to the named component
*/
boolean isDeployedServiceUnit(String componentName, String suName) throws Exception;
/**
* Returns true 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 true if the named component accepts deployments;
* false 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;
}