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