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 }