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.component; 018 019 import javax.jbi.management.DeploymentException; 020 021 /** 022 * This interface defines component-supplied methods for managing service 023 * unit deployments, and is implemented by the component. The JBI 024 * implementation queries the component for the implementation of this 025 * interface using the {@link Component#getServiceUnitManager()} method. 026 * 027 * @author JSR208 Expert Group 028 */ 029 public interface ServiceUnitManager { 030 031 /** 032 * Deploy a Service Unit to the component. This is called by the JBI 033 * implementation in order to deploy the given artifact to the implementing 034 * component. 035 * 036 * Upon successful deployment, a non-empty result string must be returned, 037 * that starts with the JBI-defined component-task-result element. For example: 038 * <pre> 039 * <component-task-result> 040 * <component-name>BC1</component-name> 041 * <component-task-result-details 042 * xmlns="http://java.sun.com/xml/ns/jbi/management-message"> 043 * <task-result-details> 044 * <task-id>deploy</task-id> 045 * <task-result>SUCCESS</task-result> 046 * </task-result-details> 047 * </component-task-result-details> 048 * </component-task-result> 049 * </pre> 050 * A failed deployment of the service unit must be reported using the 051 * <code>component-task-result</code> element as well; the 052 * <code>task-result</code> must be set to FAILED. 053 * 054 * @param serviceUnitName name of the service unit being deployed; must be 055 * non-null and non-empty and unique among service units already 056 * deployed to the component. 057 * @param serviceUnitRootPath path of the service unit artifact root, in 058 * platform specific format; must be non-null and non-empty. 059 * @return a deployment status message, which is an XML string that conforms 060 * to the schema given in the <i>MBean Status and Result Strings</i> 061 * section of the <i><b>Management</b></i> chapter of the JBI 062 * specification; must be non-null and non-empty. 063 * @exception DeploymentException if the deployment operation is 064 * unsuccessful. 065 */ 066 String deploy(String serviceUnitName, String serviceUnitRootPath) throws DeploymentException; 067 068 /** 069 * Initialize the given deployed service unit. This is the first phase of 070 * a two-phase start, where the component must prepare to receive service 071 * requests related to the deployment (if any). 072 * <p> 073 * The serviceUnitRootPath parameter is provided to facilitate restart of 074 * the component. This allows simple components to rely entirely on JBI's 075 * ability to persist deployment information, avoiding the need for the 076 * component to provide its own persistence mechanism. 077 * 078 * @param serviceUnitName name of the service unit being initialized; must 079 * be non-null, non-empty, and match the name of a previously 080 * deployed (but not yet undeployed) service unit. 081 * @param serviceUnitRootPath path of the service unit artifact root, in 082 * platform specific format; must be non-null and non-empty. 083 * @exception DeploymentException if the service unit is not deployed, or 084 * if it is in an incorrect state. 085 */ 086 void init(String serviceUnitName, String serviceUnitRootPath) throws DeploymentException; 087 088 /** 089 * Start the deployed service unit. This is the second phase of a two-phase 090 * start, where the component can now initiate service requests related to 091 * the deployment. 092 * 093 * @param serviceUnitName the name of the service unit being started; must 094 * be non-null, non-empty, and match the name of a previously 095 * deployed (but not yet undeployed) service unit. 096 * @exception DeploymentException if the service unit is not deployed, or 097 * if it is in an incorrect state. 098 */ 099 void start(String serviceUnitName) throws DeploymentException; 100 101 /** 102 * Stop the deployed service unit. This causes the component to cease 103 * generating service requests related to the given service unit. This 104 * returns the service unit to a state equivalent to after 105 * {@link #init(String, String)} was called. 106 * 107 * @param serviceUnitName name of the service unit being stopped; must 108 * be non-null, non-empty, and match the name of a previously 109 * deployed (but not yet undeployed) service unit. 110 * @exception DeploymentException if the service unit is not deployed, or 111 * if it is in an incorrect state. 112 */ 113 void stop(String serviceUnitName) throws DeploymentException; 114 115 /** 116 * Shut down the deployment. This causes the deployment to return to the 117 * to the state it was in after {@link #deploy(String, String)}, and before 118 * {@link #init(String, String)}. 119 * 120 * @param serviceUnitName name of the service unit being shut down; must 121 * be non-null, non-empty, and match the name of a previously 122 * deployed (but not yet undeployed) service unit. 123 * @exception DeploymentException if the service unit is not deployed, or 124 * if it is in an incorrect state. 125 */ 126 void shutDown(String serviceUnitName) throws DeploymentException; 127 128 /** 129 * Undeploy a service unit from the component. The service unit must be 130 * shut down to undeploy it. 131 * 132 * @param serviceUnitName name of the service unit being undeployed; must 133 * be non-null, non-empty, and match the name of a previously 134 * deployed (but not yet undeployed) service unit. 135 * @param serviceUnitRootPath path of the service unit artifact root, in 136 * platform specific format; must be non-null and non-empty. 137 * @return deployment status message, which is an XML string that conforms 138 * to the <code>component-task-result</code> type from 139 * the schema given in the <i>MBean Status and Result Strings</i> 140 * section of the <i><b>Management</b></i> chapter of the JBI 141 * specification; must be non-null and non-empty. 142 * @exception DeploymentException if undeployment operation is unsuccessful, 143 * or if the service unit is in an incorrect state. 144 */ 145 String undeploy(String serviceUnitName, String serviceUnitRootPath) throws DeploymentException; 146 }