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.xbean.kernel;
018    
019    import java.util.Set;
020    
021    /**
022     * A service factory is responsible for construction and destruction of a single service.  A service factory provides
023     * the kernel the start conditions, stopped conditions, owned services and enabled status of the service.
024     *
025     * @author Dain Sundstrom
026     * @version $Id$
027     * @since 2.0
028     */
029    public interface ServiceFactory {
030        /**
031         * Gets the types of the service this service factory will create.  These types is used to index the service within
032         * the kernel.  It is a start error to return an object from create service that is not an instance of every type.
033         * This is the only type used to index the service, so if the service factory returns a subclass of this type from
034         * createService, the subtypes will now be reflected in the index.
035         *
036         * @return the type of the service this service factory will create
037         */
038        Class[] getTypes();
039    
040        /**
041         * A restartable service can be started and stopped repeatedly in the kernel.  A service that is not restartable
042         * immediately enters the RUNNING state when registered with the kernel, and can not be started or stopped.
043         *
044         * @return true if this service can be started and stopped; false otherwise
045         */
046        boolean isRestartable();
047    
048        /**
049         * Determines if the service can be instantiated in a kernel.  A disabled restartable service can not be
050         * started and a disabled non-restartable service can not be loaded into a kernel.
051         *
052         * @return true if the service factory is enabled; false otherwise
053         */
054        boolean isEnabled();
055    
056        /**
057         * Sets the enabled status of this service factory.   A disabled restartable service can not be
058         * started and a disabled non-restartable service can not be loaded into a kernel.
059         *
060         * @param enabled the new enabled state of this factory
061         */
062        void setEnabled(boolean enabled);
063    
064        /**
065         * Get an unmodifable snapshot of the conditions that must be satisfied before this service can be started.
066         *
067         * @return the start conditions of this service
068         */
069        Set getStartConditions();
070    
071        /**
072         * Adds start condition to this service.
073         *
074         * @param startCondition the new start condition
075         * @throws NullPointerException if startCondition is null
076         */
077        void addStartCondition(ServiceCondition startCondition) throws NullPointerException;
078    
079        /**
080         * Removes a start condition from this service.
081         *
082         * @param startCondition the start condition to remove
083         * @throws NullPointerException if startCondition is null
084         */
085        void removeStartCondition(ServiceCondition startCondition) throws NullPointerException;
086    
087        /**
088         * Get an unmodifable snapshot of the conditions that must be satisfied before this service can be stopped.
089         *
090         * @return the stop conditions of this service
091         */
092        Set getStopConditions();
093    
094        /**
095         * Adds stop condition to this service.
096         *
097         * @param stopCondition the new stop condition
098         * @throws NullPointerException if stopCondition is null
099         */
100        void addStopCondition(ServiceCondition stopCondition) throws NullPointerException;
101    
102        /**
103         * Removes a stop condition from this service.
104         *
105         * @param stopCondition the stop condition to remove
106         * @throws NullPointerException if stopCondition is null
107         */
108        void removeStopCondition(ServiceCondition stopCondition) throws NullPointerException;
109    
110        /**
111         * Gets the names of services owned by this service.  This information is used for the startRecursive method on the
112         * kernel.  When a servcie is started with startRecursive all owned services will be started with startRecursive.
113         *
114         * @return the names of the services owned by this service
115         */
116        Set getOwnedServices();
117    
118        /**
119         * Creates the service instance.
120         *
121         * @param serviceContext context information for the new service
122         * @return the service instance
123         * @throws Exception if a problem occurs during construction
124         */
125        Object createService(ServiceContext serviceContext) throws Exception;
126    
127        /**
128         * Destroys the service instance.
129         *
130         * @param serviceContext the context information for the service
131         */
132        void destroyService(ServiceContext serviceContext);
133        
134        /**
135         * Gets the class loader associated with this service.
136         *
137         * @return the class loader associated with the service
138         */
139        ClassLoader getClassLoader();
140    }