001/*
002 * Copyright (c) 2006-2011 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the Eclipse Public License v1.0
006 * which accompanies this distribution, and is available at
007 * http://www.eclipse.org/legal/epl-v10.html
008 *
009 * Contributors:
010 *     Nuxeo - initial API and implementation
011 *
012 * $Id$
013 */
014
015package org.nuxeo.runtime.model;
016
017import java.io.IOException;
018import java.net.URL;
019
020import org.nuxeo.runtime.RuntimeService;
021import org.osgi.framework.Bundle;
022
023/**
024 * The runtime context.
025 * <p>
026 * Runtime contexts are used to create components. They provides custom methods to load classes and find resources.
027 * <p>
028 * Runtime contexts are generally attached to a bundle context (or module deployment context)
029 *
030 * @author <a href="mailto:bs@nuxeo.com">Bogdan Stefanescu</a>
031 */
032public interface RuntimeContext {
033
034    /**
035     * Gets the current runtime service.
036     *
037     * @return the runtime service
038     */
039    RuntimeService getRuntime();
040
041    /**
042     * Gets the container bundle or null if we are not running in an OSGi environment.
043     */
044    Bundle getBundle();
045
046    /**
047     * Loads the class given its name.
048     *
049     * @param className the class name
050     * @return the class object
051     * @throws ClassNotFoundException if no such class were found
052     * @see ClassLoader#loadClass(String)
053     */
054    Class<?> loadClass(String className) throws ClassNotFoundException;
055
056    /**
057     * Finds a resource having the given name.
058     *
059     * @param name the resource name
060     * @return an URL to the resource having that name or null if not was found
061     * @see ClassLoader#getResource(String)
062     */
063    URL getResource(String name);
064
065    /**
066     * Finds a local resource having the given name.
067     * <p>
068     * Only the current bundle should be searched for the resource.
069     *
070     * @param name the local resource name
071     * @return an URL to the resource having that name or null if not was found
072     * @see ClassLoader#getResource(String)
073     */
074    URL getLocalResource(String name);
075
076    /**
077     * Deploys a component XML descriptor given its URL.
078     * <p>
079     * Do nothing if component is already deployed.
080     * <p>
081     * Returns the registration info of the new deployed component or null if the component was not deployed.
082     *
083     * @param url the url of the XML descriptor
084     * @return the component registration info or null if registration failed for some reason
085     */
086    RegistrationInfo deploy(URL url) throws IOException;
087
088    /**
089     * Same as {@link #deploy(URL)} but using a {@link StreamRef} as argument.
090     *
091     * @param ref
092     * @return
093     */
094    RegistrationInfo deploy(StreamRef ref) throws IOException;
095
096    /**
097     * Undeploys a component XML descriptor given its URL.
098     * <p>
099     * Do nothing if no component was registered for the given URL.
100     *
101     * @param url the URL of the XML descriptor
102     */
103    void undeploy(URL url) throws IOException;
104
105    /**
106     * Same as {@link #undeploy(URL)} but using a {@link StreamRef} as stream reference.
107     *
108     * @param ref
109     */
110    void undeploy(StreamRef ref) throws IOException;
111
112    /**
113     * Checks whether the component XML file at given URL was deployed.
114     *
115     * @param url the URL to check
116     * @return true it deployed, false otherwise
117     */
118    boolean isDeployed(URL url);
119
120    /**
121     * Checks whether the component XML file given by the StreamRef argument was deployed.
122     *
123     * @param ref
124     * @return
125     */
126    boolean isDeployed(StreamRef ref);
127
128    /**
129     * Deploys the component whose XML descriptor is at the given location.
130     * <p>
131     * If the component is already deployed do nothing.
132     * <p>
133     * The location is interpreted as a relative path inside the bundle (jar) containing the component - and will be
134     * loaded using {@link RuntimeContext#getLocalResource(String)}.
135     * <p>
136     * Returns the registration info of the new deployed component or null if the component was not deployed.
137     *
138     * @param location the location
139     * @return the component registration info or null if registration failed for some reason
140     */
141    RegistrationInfo deploy(String location);
142
143    /**
144     * Undeploys the component at the given location if any was deployed.
145     * <p>
146     * If the component was not deployed do nothing.
147     *
148     * @param location the location of the component to undeploy
149     */
150    void undeploy(String location);
151
152    /**
153     * Checks if the component at the given location is deployed.
154     *
155     * @param location the component location to check
156     * @return true if deployed, false otherwise
157     */
158    boolean isDeployed(String location);
159
160    /**
161     * Destroys this context.
162     */
163    void destroy();
164
165}