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 * $Id$
020 */
021
022package org.nuxeo.runtime.model;
023
024import java.io.IOException;
025import java.net.URL;
026
027import org.nuxeo.runtime.RuntimeService;
028import org.osgi.framework.Bundle;
029
030/**
031 * The runtime context.
032 * <p>
033 * Runtime contexts are used to create components. They provides custom methods to load classes and find resources.
034 * <p>
035 * Runtime contexts are generally attached to a bundle context (or module deployment context)
036 *
037 * @author <a href="mailto:bs@nuxeo.com">Bogdan Stefanescu</a>
038 */
039public interface RuntimeContext extends AutoCloseable {
040
041    /**
042     * Gets the current runtime service.
043     *
044     * @return the runtime service
045     */
046    RuntimeService getRuntime();
047
048    /**
049     * Gets the container bundle or null if we are not running in an OSGi environment.
050     */
051    Bundle getBundle();
052
053    /**
054     * Loads the class given its name.
055     *
056     * @param className the class name
057     * @return the class object
058     * @throws ClassNotFoundException if no such class were found
059     * @see ClassLoader#loadClass(String)
060     */
061    Class<?> loadClass(String className) throws ClassNotFoundException;
062
063    /**
064     * Finds a resource having the given name.
065     *
066     * @param name the resource name
067     * @return an URL to the resource having that name or null if not was found
068     * @see ClassLoader#getResource(String)
069     */
070    URL getResource(String name);
071
072    /**
073     * Finds a local resource having the given name.
074     * <p>
075     * Only the current bundle should be searched for the resource.
076     *
077     * @param name the local resource name
078     * @return an URL to the resource having that name or null if not was found
079     * @see ClassLoader#getResource(String)
080     */
081    URL getLocalResource(String name);
082
083    /**
084     * Deploys a component XML descriptor given its URL.
085     * <p>
086     * Do nothing if component is already deployed.
087     * <p>
088     * Returns the registration info of the new deployed component or null if the component was not deployed.
089     *
090     * @param url the url of the XML descriptor
091     * @return the component registration info or null if registration failed for some reason
092     */
093    RegistrationInfo deploy(URL url) throws IOException;
094
095    /**
096     * Same as {@link #deploy(URL)} but using a {@link StreamRef} as argument.
097     *
098     * @param ref
099     * @return
100     */
101    RegistrationInfo deploy(StreamRef ref) throws IOException;
102
103    /**
104     * Undeploys a component XML descriptor given its URL.
105     * <p>
106     * Do nothing if no component was registered for the given URL.
107     *
108     * @param url the URL of the XML descriptor
109     */
110    void undeploy(URL url) throws IOException;
111
112    /**
113     * Same as {@link #undeploy(URL)} but using a {@link StreamRef} as stream reference.
114     *
115     * @param ref
116     */
117    void undeploy(StreamRef ref) throws IOException;
118
119    /**
120     * Checks whether the component XML file at given URL was deployed.
121     *
122     * @param url the URL to check
123     * @return true it deployed, false otherwise
124     */
125    boolean isDeployed(URL url);
126
127    /**
128     * Checks whether the component XML file given by the StreamRef argument was deployed.
129     *
130     * @param ref
131     * @return
132     */
133    boolean isDeployed(StreamRef ref);
134
135    /**
136     * Deploys the component whose XML descriptor is at the given location.
137     * <p>
138     * If the component is already deployed do nothing.
139     * <p>
140     * The location is interpreted as a relative path inside the bundle (jar) containing the component - and will be
141     * loaded using {@link RuntimeContext#getLocalResource(String)}.
142     * <p>
143     * Returns the registration info of the new deployed component or null if the component was not deployed.
144     *
145     * @param location the location
146     * @return the component registration info or null if registration failed for some reason
147     */
148    RegistrationInfo deploy(String location);
149
150    /**
151     * Undeploys the component at the given location if any was deployed.
152     * <p>
153     * If the component was not deployed do nothing.
154     *
155     * @param location the location of the component to undeploy
156     */
157    void undeploy(String location);
158
159    /**
160     * Checks if the component at the given location is deployed.
161     *
162     * @param location the component location to check
163     * @return true if deployed, false otherwise
164     */
165    boolean isDeployed(String location);
166
167    /**
168     * Destroys this context.
169     */
170    void destroy();
171
172    /**
173     * Destroys the context on close.
174     *
175     * @since 8.1
176     */
177    @Override
178    default void close() {
179        destroy();
180    }
181
182}