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