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 org.apache.servicemix.common;
018    
019    import java.util.Collection;
020    
021    import javax.jbi.management.DeploymentException;
022    
023    /**
024     * This interface defines the lifecycle and needed
025     * methods to a collection of endpoints grouped into
026     * a service unit.
027     */
028    public interface ServiceUnit {
029    
030        /**
031         * Retrieves the name of this service unit.
032         *
033         * @return
034         */
035        String getName();
036    
037        /**
038         * Retrieves the root path of this service unit.
039         * @return
040         */
041        String getRootPath();
042    
043        /**
044         * Retrieves the component where this SU is deployed.
045         *
046         * @return
047         */
048        ServiceMixComponent getComponent();
049    
050        /**
051         * Retrieves the list of deployed endpoints.
052         *
053         * @return
054         */
055        Collection<Endpoint> getEndpoints();
056    
057        /**
058         * Retrieve this service unit specific classloader.
059         *
060         * @return
061         */
062        ClassLoader getConfigurationClassLoader();
063    
064        /**
065         * Retrieve the state of this service unit.
066         * States can be: STOPPED, STARTED or SHUTDOWN
067         *
068         * @return
069         */
070        String getCurrentState();
071    
072        /**
073         * Puts the SU in a STOPPED state.
074         * This call is only valid if the service unit is in a SHUTDOWN state.
075         * It means it is able to process incoming exchange but will not
076         * initiate new exchanges. The process of initializing a service unit
077         * should activate all endpoints, but not start them.
078         *
079         * @throws Exception
080         * @see Endpoint#start()
081         */
082        void init() throws Exception;
083    
084        /**
085         * Transition this service unit into the STARTED state.
086         * This call is only valid if the service unit is in a STOPPED state.
087         * Start consumption of external requests by starting all
088         * the endpoints.
089         *
090         * @throws Exception
091         * @see Endpoint#start()
092         */
093        void start() throws Exception;
094    
095        /**
096         * Transition this service unit to a STOPPED state.
097         * This call is only valid if the service unit is in a STARTED state.
098         *
099         * @throws Exception
100         * @see Endpoint#stop()
101         */
102        void stop() throws Exception;
103    
104        /**
105         * Transition this service unit into the SHUTDOWN state.
106         * This call is only valid if the service unit is in a STOPPED state.
107    
108         * @throws Exception
109         * @see Endpoint#deactivate()
110         */
111        void shutDown() throws Exception;
112    
113        /**
114         * Adds an endpoint to this service unit.
115         * Adding an endpoint will transition this endpoint into a state
116         * which is consistent with this service unit state.
117         *
118         * @param ep
119         * @throws DeploymentException
120         */
121        void addEndpoint(Endpoint ep) throws DeploymentException;
122    
123        /**
124         * Removes an endpoint from this service unit.
125         * Removing an endpoint will transition it into the SHUTDOWN state.
126         *
127         * @param ep
128         * @throws DeploymentException
129         */
130        void removeEndpoint(Endpoint ep) throws DeploymentException;
131    
132    }