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