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     */
057    void stop();
058
059    /**
060     * Returns true if the runtime is started.
061     *
062     * @return true if the runtime is started, false otherwise
063     */
064    boolean isStarted();
065
066    /**
067     * Returns true if the runtime is shutting down.
068     *
069     * @return true if the runtime is shutting down, false otherwise
070     * @since 5.5
071     */
072    boolean isShuttingDown();
073
074    /**
075     * Gets the home directory of the runtime.
076     *
077     * @return the home directory
078     */
079    File getHome();
080
081    /**
082     * Gets the name of this runtime service.
083     *
084     * @return the runtime service name
085     */
086    String getName();
087
088    /**
089     * Gets the description of this runtime service.
090     *
091     * @return the runtime service description
092     */
093    String getDescription();
094
095    /**
096     * Gets the version of this runtime service.
097     *
098     * @return the runtime service version
099     */
100    Version getVersion();
101
102    /**
103     * Gets runtime service properties.
104     *
105     * @return the runtime properties
106     */
107    Properties getProperties();
108
109    /**
110     * Reread all property files loaded at startup.
111     */
112    void reloadProperties() throws IOException;
113
114    /**
115     * Gets a runtime service property given its name.
116     *
117     * @param name the property name
118     * @return the property value if any or null if none
119     */
120    String getProperty(String name);
121
122    /**
123     * Gets a property value using a default value if the property was not set.
124     *
125     * @param name the property name
126     * @param defaultValue the default value to use when the property doesn't exists
127     * @return the property value
128     */
129    String getProperty(String name, String defaultValue);
130
131    /**
132     * Replaces any substring in the form <code>${property.name}</code> with the corresponding runtime property value if
133     * any, otherwise leaves the substring unchanged.
134     *
135     * @param expression the expression to process
136     * @return the expanded expression
137     */
138    String expandVars(String expression);
139
140    /**
141     * Gets the component manager.
142     *
143     * @return the component manager
144     */
145    ComponentManager getComponentManager();
146
147    /**
148     * Gets a component given its name as a string.
149     *
150     * @param name the component name as a string
151     * @return the component
152     */
153    Object getComponent(String name);
154
155    /**
156     * Gets a component given its name.
157     *
158     * @param name the component name
159     * @return the component, or null if no such component was registered
160     */
161    Object getComponent(ComponentName name);
162
163    /**
164     * Gets a component implementation instance given its name as a string.
165     *
166     * @param name the component name as a string
167     * @return the component
168     */
169    ComponentInstance getComponentInstance(String name);
170
171    /**
172     * Gets a component implementation instance given its name.
173     *
174     * @param name the component name
175     * @return the component or null if no such component was registered
176     */
177    ComponentInstance getComponentInstance(ComponentName name);
178
179    /**
180     * Gets the context of the runtime bundle.
181     *
182     * @return the context object
183     */
184    RuntimeContext getContext();
185
186    /**
187     * Gets the service of type serviceClass if such a service was declared by a resolved runtime component.
188     * <p>
189     * If the component is not yet activated, it will be prior to return the service.
190     *
191     * @param <T> the service type
192     * @param serviceClass the service class
193     * @return the service object
194     */
195    <T> T getService(Class<T> serviceClass);
196
197    /**
198     * Gets a list of startup warnings. Can be modified to add new warnings.
199     * <p />
200     * Warning messages don't block server startup.
201     *
202     * @return the warning list
203     */
204    List<String> getWarnings();
205
206    /**
207     * Gets a list of startup errors. Can be modified to add new errors.
208     * <p />
209     * Error messages block server startup in strict mode.
210     *
211     * @return the error list
212     * @since 9.1
213     */
214    List<String> getErrors();
215
216    /**
217     * OSGi frameworks are using a string {@link Bundle#getLocation()} to identify bundle locations.
218     * <p>
219     * This method try to convert the bundle location to real file if possible. If this bundle location cannot be
220     * converted to a file (e.g. it may be a remote URL), null is returned.
221     * <p>
222     * This method works only for bundles that are installed as files on the host file system.
223     *
224     * @return the bundle file, or null
225     */
226    File getBundleFile(Bundle bundle);
227
228    /**
229     * Get an installed bundle given its symbolic name. This method is not handling versions.
230     */
231    Bundle getBundle(String symbolicName);
232
233    /**
234     * Computes the runtime status, adds it to the given string builder, and return true if some problems have been
235     * detected.
236     *
237     * @since 5.6
238     * @return true if there are warnings/errors on current runtime.
239     */
240    boolean getStatusMessage(StringBuilder msg);
241
242    /**
243     * @since 7.4
244     */
245    void setProperty(String name, Object value);
246
247}