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