001/*
002 * (C) Copyright 2006-2019 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     * @since 5.5
071     * @see #reloadProperties()
072     */
073    void reload() throws InterruptedException;
074
075    /**
076     * Reloads runtime framework properties
077     */
078    void reloadProperties() throws IOException;
079
080    /**
081     * Sends a runtime event with id {@link #RELOAD_SEAM_EVENT_ID}
082     *
083     * @since 5.5
084     */
085    void reloadSeamComponents();
086
087    /**
088     * Sends a runtime event with id {@link #FLUSH_EVENT_ID} so that listeners can be notified that a flush is needed
089     * (after a reload for instance).
090     * <p>
091     * Also calls {@link #flushJaasCache()} by default, but not other flush methods as they could alter the running
092     * application behaviour.
093     *
094     * @see #flushJaasCache()
095     * @since 5.5
096     */
097    void flush();
098
099    /**
100     * Returns the last time one of the flush commands where called on this service instance ({@link #flush()} or
101     * {@link #flushJaasCache()} or {@link #flushSeamComponents()}, or null if never called.
102     *
103     * @since 5.6
104     */
105    Long lastFlushed();
106
107    /**
108     * Sends an event that can trigger reset of JaasCache.
109     */
110    void flushJaasCache();
111
112    /**
113     * Sends a runtime event with id {@link #FLUSH_SEAM_EVENT_ID}.
114     *
115     * @since 5.6
116     */
117    void flushSeamComponents();
118
119    /**
120     * Deploys bundle to the runtime, without reloading resources.
121     *
122     * @since 5.5
123     * @see #deployBundles(List, boolean)
124     * @deprecated since 9.3 use {@link #reloadBundles(ReloadContext)} instead. Kept for backward compatibility.
125     */
126    @Deprecated(since = "9.3")
127    default void deployBundle(File file) throws BundleException {
128        deployBundle(file, false);
129    }
130
131    /**
132     * Deploys bundle to the runtime, gives possibility to control resources reloading.
133     *
134     * @since 5.5
135     * @see #deployBundles(List, boolean)
136     * @deprecated since 9.3 use {@link #reloadBundles(ReloadContext)} instead. Kept for backward compatibility.
137     */
138    @Deprecated(since = "9.3")
139    default void deployBundle(File file, boolean reloadResources) throws BundleException {
140        deployBundles(Collections.singletonList(file), reloadResources);
141    }
142
143    /**
144     * Deploys bundles to the runtime, without reloading resources.
145     *
146     * @since 9.3
147     * @see #deployBundles(List, boolean)
148     * @deprecated since 9.3 use {@link #reloadBundles(ReloadContext)} instead. Kept for backward compatibility.
149     */
150    @Deprecated(since = "9.3")
151    default void deployBundles(List<File> files) throws BundleException {
152        deployBundles(files, false);
153    }
154
155    /**
156     * Deploys bundles to the runtime, gives possibility to control resources reloading.
157     *
158     * @since 9.3
159     * @deprecated since 9.3 use {@link #reloadBundles(ReloadContext)} instead. Kept for backward compatibility.
160     */
161    @Deprecated(since = "9.3")
162    void deployBundles(List<File> files, boolean reloadResources) throws BundleException;
163
164    /**
165     * Undeploys bundle from the runtime, without reloading resources.
166     *
167     * @since 5.6
168     * @see #undeployBundles(List, boolean)
169     * @deprecated since 9.3 use {@link #reloadBundles(ReloadContext)} instead. Kept for backward compatibility.
170     */
171    @Deprecated(since = "9.3")
172    default void undeployBundle(String bundleName) throws BundleException {
173        undeployBundle(bundleName, false);
174    }
175
176    /**
177     * Undeploys bundle from the runtime, gives possibility to control resources reloading.
178     *
179     * @since 9.3
180     * @see #undeployBundles(List, boolean)
181     * @deprecated since 9.3 use {@link #reloadBundles(ReloadContext)} instead. Kept for backward compatibility.
182     */
183    @Deprecated(since = "9.3")
184    default void undeployBundle(String bundleName, boolean reloadResources) throws BundleException {
185        undeployBundles(Collections.singletonList(bundleName), reloadResources);
186    }
187
188    /**
189     * Undeploys bundles from the runtime, without reloading resources.
190     *
191     * @since 9.3
192     * @see #undeployBundles(List, boolean)
193     * @deprecated since 9.3 use {@link #reloadBundles(ReloadContext)} instead. Kept for backward compatibility.
194     */
195    @Deprecated(since = "9.3")
196    default void undeployBundles(List<String> bundleNames) throws BundleException {
197        undeployBundles(bundleNames, false);
198    }
199
200    /**
201     * Undeploys bundles from the runtime, gives possibility to control resources reloading.
202     *
203     * @since 9.3
204     * @deprecated since 9.3 use {@link #reloadBundles(ReloadContext)} instead. Kept for backward compatibility.
205     */
206    @Deprecated(since = "9.3")
207    void undeployBundles(List<String> bundleNames, boolean reloadResources) throws BundleException;
208
209    /**
210     * Called by ReloadServiceInvoker#hotReloadBundles.
211     *
212     * @return the result of hot reload operation
213     * @since 9.3
214     */
215    ReloadResult reloadBundles(ReloadContext context) throws BundleException;
216
217    /**
218     * Runs the deployment preprocessor.
219     *
220     * @since 5.6
221     * @see DeploymentPreprocessor
222     */
223    void runDeploymentPreprocessor() throws IOException;
224
225    /**
226     * Copies the bundle web resources into the nuxeo WAR directory.
227     *
228     * @since 5.5
229     * @deprecated since 5.6: use {@link #runDeploymentPreprocessor()} method instead, now re-deploys all jars so that
230     *             the nuxeo.war holds the same content than it would at startup. This method is called by reflection by
231     *             ReloadServiceInvoker#hotDeployBundles. Keep it as compatibility code until NXP-9642 is done.
232     */
233    @Deprecated
234    void installWebResources(File file) throws IOException;
235
236    /***
237     * Returns the OSGI bundle name if given file can be identified as an OSGI bundle, or null. The OSGI bundle can be a
238     * jar or an exploded jar on file system.
239     *
240     * @since 5.6
241     */
242    String getOSGIBundleName(File file);
243
244}