001/*
002 * (C) Copyright 2006-2015 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 *
016 * Contributors:
017 *     Nuxeo - initial API and implementation
018 *
019 */
020
021package org.nuxeo.runtime;
022
023import java.io.File;
024import java.io.IOException;
025import java.util.List;
026import java.util.Properties;
027
028import org.nuxeo.runtime.model.ComponentInstance;
029import org.nuxeo.runtime.model.ComponentManager;
030import org.nuxeo.runtime.model.ComponentName;
031import org.nuxeo.runtime.model.RuntimeContext;
032import org.osgi.framework.Bundle;
033
034/**
035 * The runtime service: a singleton object that provides access to the Nuxeo Runtime. The runtime service must be
036 * started before any other runtime component or object that accesses the runtime.
037 * <p>
038 * This service is usually implemented for each target platform where Nuxeo Runtime should run.
039 * <p>
040 * It is recommended to extend the {@link AbstractRuntimeService} class instead of directly implementing this interface.
041 * <p>
042 * After the runtime service was initialized, it may be accessed through the facade class
043 * {@link org.nuxeo.runtime.api.Framework}.
044 * <p>
045 * See: {@link org.nuxeo.runtime.api.Framework}
046 *
047 * @author <a href="mailto:bs@nuxeo.com">Bogdan Stefanescu</a>
048 */
049public interface RuntimeService {
050
051    /**
052     * Starts the runtime.
053     */
054    void start();
055
056    /**
057     * Stops the runtime.
058     */
059    void stop();
060
061    /**
062     * Returns true if the runtime is started.
063     *
064     * @return true if the runtime is started, false otherwise
065     */
066    boolean isStarted();
067
068    /**
069     * Returns true if the runtime is shutting down.
070     *
071     * @return true if the runtime is shutting down, false otherwise
072     * @since 5.5
073     */
074    boolean isShuttingDown();
075
076    /**
077     * Gets the home directory of the runtime.
078     *
079     * @return the home directory
080     */
081    File getHome();
082
083    /**
084     * Gets the name of this runtime service.
085     *
086     * @return the runtime service name
087     */
088    String getName();
089
090    /**
091     * Gets the description of this runtime service.
092     *
093     * @return the runtime service description
094     */
095    String getDescription();
096
097    /**
098     * Gets the version of this runtime service.
099     *
100     * @return the runtime service version
101     */
102    Version getVersion();
103
104    /**
105     * Gets runtime service properties.
106     *
107     * @return the runtime properties
108     */
109    Properties getProperties();
110
111    /**
112     * Reread all property files loaded at startup.
113     */
114    void reloadProperties() throws IOException;
115
116    /**
117     * Gets a runtime service property given its name.
118     *
119     * @param name the property name
120     * @return the property value if any or null if none
121     */
122    String getProperty(String name);
123
124    /**
125     * Gets a property value using a default value if the property was not set.
126     *
127     * @param name the property name
128     * @param defaultValue the default value to use when the property doesn't exists
129     * @return the property value
130     */
131    String getProperty(String name, String defaultValue);
132
133    /**
134     * Replaces any substring in the form <code>${property.name}</code> with the corresponding runtime property value if
135     * any, otherwise leaves the substring unchanged.
136     *
137     * @param expression the expression to process
138     * @return the expanded expression
139     */
140    String expandVars(String expression);
141
142    /**
143     * Gets the component manager.
144     *
145     * @return the component manager
146     */
147    ComponentManager getComponentManager();
148
149    /**
150     * Gets a component given its name as a string.
151     *
152     * @param name the component name as a string
153     * @return the component
154     */
155    Object getComponent(String name);
156
157    /**
158     * Gets a component given its name.
159     *
160     * @param name the component name
161     * @return the component, or null if no such component was registered
162     */
163    Object getComponent(ComponentName name);
164
165    /**
166     * Gets a component implementation instance given its name as a string.
167     *
168     * @param name the component name as a string
169     * @return the component
170     */
171    ComponentInstance getComponentInstance(String name);
172
173    /**
174     * Gets a component implementation instance given its name.
175     *
176     * @param name the component name
177     * @return the component or null if no such component was registered
178     */
179    ComponentInstance getComponentInstance(ComponentName name);
180
181    /**
182     * Gets the context of the runtime bundle.
183     *
184     * @return the context object
185     */
186    RuntimeContext getContext();
187
188    /**
189     * Gets the service of type serviceClass if such a service was declared by a resolved runtime component.
190     * <p>
191     * If the component is not yet activated, it will be prior to return the service.
192     *
193     * @param <T> the service type
194     * @param serviceClass the service class
195     * @return the service object
196     */
197    <T> T getService(Class<T> serviceClass);
198
199    /**
200     * Gets a list of startup warnings. Can be modified to add new warnings.
201     *
202     * @return the warning list
203     */
204    List<String> getWarnings();
205
206    /**
207     * OSGi frameworks are using a string {@link Bundle#getLocation()} to identify bundle locations.
208     * <p>
209     * This method try to convert the bundle location to real file if possible. If this bundle location cannot be
210     * converted to a file (e.g. it may be a remote URL), null is returned.
211     * <p>
212     * This method works only for bundles that are installed as files on the host file system.
213     *
214     * @return the bundle file, or null
215     */
216    File getBundleFile(Bundle bundle);
217
218    /**
219     * Get an installed bundle given its symbolic name. This method is not handling versions.
220     *
221     * @param symbolicName
222     */
223    Bundle getBundle(String symbolicName);
224
225    /**
226     * Computes the runtime status, adds it to the given string builder, and return true if some problems have been
227     * detected.
228     *
229     * @since 5.6
230     * @param msg
231     * @return true if there are warnings/errors on current runtime.
232     */
233    boolean getStatusMessage(StringBuilder msg);
234
235    /**
236     * @since 7.4
237     */
238    void setProperty(String name, Object value);
239
240}