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 *     bstefanescu
018 *     Kevin Leturc <kleturc@nuxeo.com>
019 */
020package org.nuxeo.runtime.reload;
021
022import java.io.File;
023import java.io.IOException;
024import java.util.Collections;
025import java.util.List;
026
027import org.nuxeo.runtime.deployment.preprocessor.DeploymentPreprocessor;
028import org.nuxeo.runtime.service.TimestampedService;
029import org.osgi.framework.BundleException;
030
031/**
032 * Service tracking reload related events or commands when installing a package.
033 * <p />
034 * WARNING: This interface is used by reflection in org.nuxeo.runtime.tomcat.dev.ReloadServiceInvoker.
035 *
036 * @author <a href="mailto:bs@nuxeo.com">Bogdan Stefanescu</a>
037 */
038public interface ReloadService extends TimestampedService {
039
040    String RELOAD_TOPIC = "org.nuxeo.runtime.reload";
041
042    String FLUSH_EVENT_ID = "flush";
043
044    String BEFORE_RELOAD_EVENT_ID = "before-reload";
045
046    String RELOAD_EVENT_ID = "reload";
047
048    String AFTER_RELOAD_EVENT_ID = "after-reload";
049
050    String FLUSH_SEAM_EVENT_ID = FLUSH_EVENT_ID + "SeamComponents";
051
052    String RELOAD_SEAM_EVENT_ID = "reloadSeamComponents";
053
054    /**
055     * This property allows to use the former way to hot reload Nuxeo server.
056     * <p/>
057     * The property and the former mechanism will be removed in the next LTS version.
058     *
059     * @since 9.3
060     */
061    String USE_COMPAT_HOT_RELOAD = "nuxeo.hotreload.compat.mechanism";
062
063    /**
064     * Sends a runtime event with id {@link #RELOAD_EVENT_ID} so that listeners can be notified that a reload has been
065     * done.
066     * <p>
067     * Also calls {@link #reloadProperties()} by default, but not other reload methods as they could alter the running
068     * application behaviour.
069     *
070     * @throws InterruptedException
071     * @since 5.5
072     * @see #reloadProperties()
073     */
074    void reload() throws InterruptedException;
075
076    /**
077     * Reloads runtime framework properties
078     */
079    void reloadProperties() throws IOException;
080
081    /**
082     * Sends a runtime event with id {@link #RELOAD_SEAM_EVENT_ID}
083     *
084     * @since 5.5
085     */
086    void reloadSeamComponents();
087
088    /**
089     * Sends a runtime event with id {@link #FLUSH_EVENT_ID} so that listeners can be notified that a flush is needed
090     * (after a reload for instance).
091     * <p>
092     * Also calls {@link #flushJaasCache()} by default, but not other flush methods as they could alter the running
093     * application behaviour.
094     *
095     * @see {@link #flushJaasCache()}
096     * @since 5.5
097     */
098    void flush();
099
100    /**
101     * Returns the last time one of the flush commands where called on this service instance ({@link #flush()} or
102     * {@link #flushJaasCache()} or {@link #flushSeamComponents()}, or null if never called.
103     *
104     * @since 5.6
105     */
106    Long lastFlushed();
107
108    /**
109     * Sends an event that can trigger reset of JaasCache.
110     */
111    void flushJaasCache();
112
113    /**
114     * Sends a runtime event with id {@link #FLUSH_SEAM_EVENT_ID}.
115     *
116     * @since 5.6
117     */
118    void flushSeamComponents();
119
120    /**
121     * Deploys bundle to the runtime, without reloading resources.
122     *
123     * @since 5.5
124     * @see #deployBundles(List, boolean)
125     * @deprecated since 9.3 use {@link #reloadBundles(List, List)} instead. Kept for backward compatibility.
126     */
127    @Deprecated
128    default void deployBundle(File file) throws BundleException {
129        deployBundle(file, false);
130    }
131
132    /**
133     * Deploys bundle to the runtime, gives possibility to control resources reloading.
134     *
135     * @since 5.5
136     * @see #deployBundles(List, boolean)
137     * @deprecated since 9.3 use {@link #reloadBundles(List, List)} instead. Kept for backward compatibility.
138     */
139    @Deprecated
140    default void deployBundle(File file, boolean reloadResources) throws BundleException {
141        deployBundles(Collections.singletonList(file), reloadResources);
142    }
143
144    /**
145     * Deploys bundles to the runtime, without reloading resources.
146     *
147     * @since 9.3
148     * @see #deployBundles(List, boolean)
149     * @deprecated since 9.3 use {@link #reloadBundles(List, List)} instead. Kept for backward compatibility.
150     */
151    @Deprecated
152    default void deployBundles(List<File> files) throws BundleException {
153        deployBundles(files, false);
154    }
155
156    /**
157     * Deploys bundles to the runtime, gives possibility to control resources reloading.
158     *
159     * @since 9.3
160     * @deprecated since 9.3 use {@link #reloadBundles(List, List)} instead. Kept for backward compatibility.
161     */
162    @Deprecated
163    void deployBundles(List<File> files, boolean reloadResources) throws BundleException;
164
165    /**
166     * Undeploys bundle from the runtime, without reloading resources.
167     *
168     * @since 5.6
169     * @see #undeployBundles(List, boolean)
170     * @deprecated since 9.3 use {@link #reloadBundles(List, List)} instead. Kept for backward compatibility.
171     */
172    @Deprecated
173    default void undeployBundle(String bundleName) throws BundleException {
174        undeployBundle(bundleName, false);
175    }
176
177    /**
178     * Undeploys bundle from the runtime, gives possibility to control resources reloading.
179     *
180     * @since 9.3
181     * @see #undeployBundles(List, boolean)
182     * @deprecated since 9.3 use {@link #reloadBundles(List, List)} instead. Kept for backward compatibility.
183     */
184    @Deprecated
185    default void undeployBundle(String bundleName, boolean reloadResources) throws BundleException {
186        undeployBundles(Collections.singletonList(bundleName), reloadResources);
187    }
188
189    /**
190     * Undeploys bundles from the runtime, without reloading resources.
191     *
192     * @since 9.3
193     * @see #undeployBundles(List, boolean)
194     * @deprecated since 9.3 use {@link #reloadBundles(List, List)} instead. Kept for backward compatibility.
195     */
196    @Deprecated
197    default void undeployBundles(List<String> bundleNames) throws BundleException {
198        undeployBundles(bundleNames, false);
199    }
200
201    /**
202     * Undeploys bundles from the runtime, gives possibility to control resources reloading.
203     *
204     * @since 9.3
205     * @deprecated since 9.3 use {@link #reloadBundles(List, List)} instead. Kept for backward compatibility.
206     */
207    @Deprecated
208    void undeployBundles(List<String> bundleNames, boolean reloadResources) throws BundleException;
209
210    /**
211     * Called by ReloadServiceInvoker#hotReloadBundles.
212     *
213     * @return the result of hot reload operation
214     * @since 9.3
215     */
216    ReloadResult reloadBundles(ReloadContext context) throws BundleException;
217
218    /**
219     * Runs the deployment preprocessor.
220     *
221     * @since 5.6
222     * @see {@link DeploymentPreprocessor}
223     */
224    void runDeploymentPreprocessor() throws IOException;
225
226    /**
227     * Copies the bundle web resources into the nuxeo WAR directory.
228     *
229     * @since 5.5
230     * @deprecated since 5.6: use {@link #runDeploymentPreprocessor()} method instead, now re-deploys all jars so that
231     *             the nuxeo.war holds the same content than it would at startup. This method is called by reflection by
232     *             ReloadServiceInvoker#hotDeployBundles. Keep it as compatibility code until NXP-9642 is done.
233     */
234    @Deprecated
235    void installWebResources(File file) throws IOException;
236
237    /***
238     * Returns the OSGI bundle name if given file can be identified as an OSGI bundle, or null. The OSGI bundle can be a
239     * jar or an exploded jar on file system.
240     *
241     * @since 5.6
242     */
243    String getOSGIBundleName(File file);
244
245}