001/*
002 * (C) Copyright 2006-2011 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 *     Bogdan Stefanescu
018 *     Damien Metzler (Leroy Merlin, http://www.leroymerlin.fr/)
019 */
020package org.nuxeo.runtime.test.runner;
021
022import java.io.File;
023import java.net.URISyntaxException;
024import java.net.URL;
025import java.util.List;
026import java.util.Properties;
027
028import org.nuxeo.osgi.OSGiAdapter;
029import org.nuxeo.runtime.model.RuntimeContext;
030import org.nuxeo.runtime.test.WorkingDirectoryConfigurator;
031
032/**
033 * TODO: Move this to org.nuxeo.runtime package
034 *
035 * @author <a href="mailto:bs@nuxeo.com">Bogdan Stefanescu</a>
036 */
037public interface RuntimeHarness {
038
039    /**
040     * Gets the framework working directory.
041     */
042    File getWorkingDir();
043
044    /**
045     * Fires the event {@code FrameworkEvent.STARTED}.
046     */
047    void fireFrameworkStarted() throws Exception;
048
049    /**
050     * Deploys a whole OSGI bundle.
051     * <p>
052     * The lookup is first done on symbolic name, as set in <code>MANIFEST.MF</code> and then falls back to the bundle
053     * url (e.g., <code>nuxeo-platform-search-api</code>) for backwards compatibility.
054     *
055     * @param bundle the symbolic name
056     */
057    void deployBundle(String bundle) throws Exception;
058
059    /**
060     * Undeploys a contribution from a given bundle.
061     * <p>
062     * The path will be relative to the bundle root. Example: <code>
063     * undeployContrib("org.nuxeo.ecm.core", "OSGI-INF/CoreExtensions.xml")
064     * </code>
065     *
066     * @param bundle the bundle
067     * @param contrib the contribution
068     */
069    void undeployContrib(String bundle, String contrib) throws Exception;
070
071    /**
072     * @deprecated use {@link #undeployContrib(String, String)} instead
073     */
074    @Deprecated
075    void undeployContrib(String contrib);
076
077    /**
078     * @deprecated use {@link #undeployContrib(String, String)} instead
079     */
080    @Deprecated
081    void undeploy(String contrib);
082
083    RuntimeContext deployTestContrib(String bundle, URL contrib) throws Exception;
084
085    /**
086     * Deploys an XML contribution from outside a bundle.
087     * <p>
088     * This should be used by tests wiling to deploy test contribution as part of a real bundle.
089     * <p>
090     * The bundle owner is important since the contribution may depend on resources deployed in that bundle.
091     * <p>
092     * Note that the owner bundle MUST be an already deployed bundle.
093     *
094     * @param bundle the bundle that becomes the contribution owner
095     * @param contrib the contribution to deploy as part of the given bundle
096     */
097    RuntimeContext deployTestContrib(String bundle, String contrib) throws Exception;
098
099    /**
100     * Deploys a contribution from a given bundle.
101     * <p>
102     * The path will be relative to the bundle root. Example: <code>
103     * deployContrib("org.nuxeo.ecm.core", "OSGI-INF/CoreExtensions.xml")
104     * </code>
105     * <p>
106     * For compatibility reasons the name of the bundle may be a jar name, but this use is discouraged and deprecated.
107     *
108     * @param bundle the name of the bundle to peek the contrib in
109     * @param contrib the path to contrib in the bundle.
110     */
111    void deployContrib(String bundle, String contrib) throws Exception;
112
113    /**
114     * Deploys a contribution file by looking for it in the class loader.
115     * <p>
116     * The first contribution file found by the class loader will be used. You have no guarantee in case of name
117     * collisions.
118     *
119     * @deprecated use the less ambiguous {@link #deployContrib(String, String)}
120     * @param contrib the relative path to the contribution file
121     */
122    @Deprecated
123    void deployContrib(String contrib);
124
125    /**
126     * @deprecated use <code>deployContrib()</code> instead
127     */
128    @Deprecated
129    void deploy(String contrib);
130
131    void start() throws Exception;
132
133    void stop() throws Exception;
134
135    boolean isStarted();
136
137    void deployFolder(File folder, ClassLoader loader) throws Exception;
138
139    void addWorkingDirectoryConfigurator(WorkingDirectoryConfigurator config);
140
141    /**
142     * Framework properties for variable injections
143     *
144     * @since 5.4.2
145     */
146    Properties getProperties();
147
148    /**
149     * Runtime context for deployment
150     *
151     * @since 5.4.2
152     */
153    RuntimeContext getContext();
154
155    /**
156     * OSGI bridge
157     *
158     * @since 5.4.2
159     */
160    OSGiAdapter getOSGiAdapter();
161
162    /**
163     * @since 5.5
164     */
165    public boolean isRestart();
166
167    /**
168     * @since 5.5
169     * @throws Exception
170     */
171    public void restart() throws Exception;
172
173    /**
174     * @throws URISyntaxException
175     * @since 5.7
176     */
177    public List<String> getClassLoaderFiles() throws URISyntaxException;
178
179}