Java tutorial
/* * (C) Copyright 2006-2016 Nuxeo SA (http://nuxeo.com/) and others. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. * * Contributors: * Nuxeo - initial API and implementation * */ package org.nuxeo.runtime.api; import java.io.File; import java.io.IOException; import java.net.MalformedURLException; import java.net.URL; import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.attribute.FileAttribute; import java.util.List; import java.util.Properties; import java.util.function.Supplier; import javax.security.auth.callback.CallbackHandler; import javax.security.auth.login.LoginContext; import javax.security.auth.login.LoginException; import org.apache.commons.io.FileDeleteStrategy; import org.apache.commons.lang.StringUtils; import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; import org.nuxeo.common.Environment; import org.nuxeo.common.collections.ListenerList; import org.nuxeo.runtime.RuntimeService; import org.nuxeo.runtime.RuntimeServiceEvent; import org.nuxeo.runtime.RuntimeServiceException; import org.nuxeo.runtime.RuntimeServiceListener; import org.nuxeo.runtime.api.login.LoginAs; import org.nuxeo.runtime.api.login.LoginService; import org.nuxeo.runtime.trackers.files.FileEvent; import org.nuxeo.runtime.trackers.files.FileEventTracker; /** * This class is the main entry point to a Nuxeo runtime application. * <p> * It offers an easy way to create new sessions, to access system services and other resources. * <p> * There are two type of services: * <ul> * <li>Global Services - these services are uniquely defined by a service class, and there is an unique instance of the * service in the system per class. * <li>Local Services - these services are defined by a class and an URI. This type of service allows multiple service * instances for the same class of services. Each instance is uniquely defined in the system by an URI. * </ul> * * @author <a href="mailto:bs@nuxeo.com">Bogdan Stefanescu</a> */ public final class Framework { private static final Log log = LogFactory.getLog(Framework.class); private static Boolean testModeSet; /** * Global dev property * * @since 5.6 * @see #isDevModeSet() */ public static final String NUXEO_DEV_SYSTEM_PROP = "org.nuxeo.dev"; /** * Global testing property * * @since 5.6 * @see #isTestModeSet() */ public static final String NUXEO_TESTING_SYSTEM_PROP = "org.nuxeo.runtime.testing"; /** * Property to control strict runtime mode * * @since 5.6 * @see #handleDevError(Throwable) */ public static final String NUXEO_STRICT_RUNTIME_SYSTEM_PROP = "org.nuxeo.runtime.strict"; /** * The runtime instance. */ private static RuntimeService runtime; private static final ListenerList listeners = new ListenerList(); /** * A class loader used to share resources between all bundles. * <p> * This is useful to put resources outside any bundle (in a directory on the file system) and then refer them from * XML contributions. * <p> * The resource directory used by this loader is ${nuxeo_data_dir}/resources whee ${nuxeo_data_dir} is usually * ${nuxeo_home}/data */ protected static SharedResourceLoader resourceLoader; /** * Whether or not services should be exported as OSGI services. This is controlled by the ${ecr.osgi.services} * property. The default is false. */ protected static Boolean isOSGiServiceSupported; // Utility class. private Framework() { } public static void initialize(RuntimeService runtimeService) { if (runtime != null) { throw new RuntimeServiceException("Nuxeo Framework was already initialized"); } runtime = runtimeService; reloadResourceLoader(); runtime.start(); } public static void reloadResourceLoader() { File rs = new File(Environment.getDefault().getData(), "resources"); rs.mkdirs(); URL url; try { url = rs.toURI().toURL(); } catch (MalformedURLException e) { throw new RuntimeServiceException(e); } resourceLoader = new SharedResourceLoader(new URL[] { url }, Framework.class.getClassLoader()); } /** * Reload the resources loader, keeping URLs already tracked, and adding possibility to add or remove some URLs. * <p> * Useful for hot reload of jars. * * @since 5.6 */ public static void reloadResourceLoader(List<URL> urlsToAdd, List<URL> urlsToRemove) { File rs = new File(Environment.getDefault().getData(), "resources"); rs.mkdirs(); URL[] existing = null; if (resourceLoader != null) { existing = resourceLoader.getURLs(); } // reinit URL url; try { url = rs.toURI().toURL(); } catch (MalformedURLException e) { throw new RuntimeException(e); } resourceLoader = new SharedResourceLoader(new URL[] { url }, Framework.class.getClassLoader()); // add back existing urls unless they should be removed, and add new // urls if (existing != null) { for (URL oldURL : existing) { if (urlsToRemove == null || !urlsToRemove.contains(oldURL)) { resourceLoader.addURL(oldURL); } } } if (urlsToAdd != null) { for (URL newURL : urlsToAdd) { resourceLoader.addURL(newURL); } } } public static void shutdown() { if (runtime == null) { throw new IllegalStateException("runtime not exist"); } try { runtime.stop(); } finally { runtime = null; } } /** * Tests whether or not the runtime was initialized. * * @return true if the runtime was initialized, false otherwise */ public static synchronized boolean isInitialized() { return runtime != null; } public static SharedResourceLoader getResourceLoader() { return resourceLoader; } /** * Gets the runtime service instance. * * @return the runtime service instance */ public static RuntimeService getRuntime() { return runtime; } /** * Gets a service given its class. */ public static <T> T getService(Class<T> serviceClass) { ServiceProvider provider = DefaultServiceProvider.getProvider(); if (provider != null) { return provider.getService(serviceClass); } checkRuntimeInitialized(); // TODO impl a runtime service provider return runtime.getService(serviceClass); } /** * Gets a service given its class. */ public static <T> T getLocalService(Class<T> serviceClass) { return getService(serviceClass); } /** * Lookup a registered object given its key. */ public static Object lookup(String key) { return null; // TODO } /** * Runs the given {@link Runnable} while logged in as a system user. * * @param runnable what to run * @since 8.4 */ public static void doPrivileged(Runnable runnable) { try { LoginContext loginContext = login(); try { runnable.run(); } finally { if (loginContext != null) { // may be null in tests loginContext.logout(); } } } catch (LoginException e) { throw new RuntimeException(e); } } /** * Calls the given {@link Supplier} while logged in as a system user and returns its result. * * @param supplier what to call * @return the supplier's result * @since 8.4 */ public static <T> T doPrivileged(Supplier<T> supplier) { try { LoginContext loginContext = login(); try { return supplier.get(); } finally { if (loginContext != null) { // may be null in tests loginContext.logout(); } } } catch (LoginException e) { throw new RuntimeException(e); } } /** * Login in the system as the system user (a pseudo-user having all privileges). * * @return the login session if successful. Never returns null. * @throws LoginException on login failure */ public static LoginContext login() throws LoginException { checkRuntimeInitialized(); LoginService loginService = runtime.getService(LoginService.class); if (loginService != null) { return loginService.login(); } return null; } /** * Login in the system as the system user (a pseudo-user having all privileges). The given username will be used to * identify the user id that called this method. * * @param username the originating user id * @return the login session if successful. Never returns null. * @throws LoginException on login failure */ public static LoginContext loginAs(String username) throws LoginException { checkRuntimeInitialized(); LoginService loginService = runtime.getService(LoginService.class); if (loginService != null) { return loginService.loginAs(username); } return null; } /** * Login in the system as the given user without checking the password. * * @param username the user name to login as. * @return the login context * @throws LoginException if any error occurs * @since 5.4.2 */ public static LoginContext loginAsUser(String username) throws LoginException { return getLocalService(LoginAs.class).loginAs(username); } /** * Login in the system as the given user using the given password. * * @param username the username to login * @param password the password * @return a login session if login was successful. Never returns null. * @throws LoginException if login failed */ public static LoginContext login(String username, Object password) throws LoginException { checkRuntimeInitialized(); LoginService loginService = runtime.getService(LoginService.class); if (loginService != null) { return loginService.login(username, password); } return null; } /** * Login in the system using the given callback handler for login info resolution. * * @param cbHandler used to fetch the login info * @return the login context * @throws LoginException */ public static LoginContext login(CallbackHandler cbHandler) throws LoginException { checkRuntimeInitialized(); LoginService loginService = runtime.getService(LoginService.class); if (loginService != null) { return loginService.login(cbHandler); } return null; } public static void sendEvent(RuntimeServiceEvent event) { Object[] listenersArray = listeners.getListeners(); for (Object listener : listenersArray) { ((RuntimeServiceListener) listener).handleEvent(event); } } /** * Registers a listener to be notified about runtime events. * <p> * If the listener is already registered, do nothing. * * @param listener the listener to register */ public static void addListener(RuntimeServiceListener listener) { listeners.add(listener); } /** * Removes the given listener. * <p> * If the listener is not registered, do nothing. * * @param listener the listener to remove */ public static void removeListener(RuntimeServiceListener listener) { listeners.remove(listener); } /** * Gets the given property value if any, otherwise null. * <p> * The framework properties will be searched first then if any matching property is found the system properties are * searched too. * * @param key the property key * @return the property value if any or null otherwise */ public static String getProperty(String key) { return getProperty(key, null); } /** * Gets the given property value if any, otherwise returns the given default value. * <p> * The framework properties will be searched first then if any matching property is found the system properties are * searched too. * * @param key the property key * @param defValue the default value to use * @return the property value if any otherwise the default value */ public static String getProperty(String key, String defValue) { checkRuntimeInitialized(); return runtime.getProperty(key, defValue); } /** * Gets all the framework properties. The system properties are not included in the returned map. * * @return the framework properties map. Never returns null. */ public static Properties getProperties() { checkRuntimeInitialized(); return runtime.getProperties(); } /** * Expands any variable found in the given expression with the value of the corresponding framework property. * <p> * The variable format is ${property_key}. * <p> * System properties are also expanded. */ public static String expandVars(String expression) { checkRuntimeInitialized(); return runtime.expandVars(expression); } public static boolean isOSGiServiceSupported() { if (isOSGiServiceSupported == null) { isOSGiServiceSupported = Boolean.valueOf(isBooleanPropertyTrue("ecr.osgi.services")); } return isOSGiServiceSupported.booleanValue(); } /** * Returns true if dev mode is set. * <p> * Activating this mode, some of the code may not behave as it would in production, to ease up debugging and working * on developing the application. * <p> * For instance, it'll enable hot-reload if some packages are installed while the framework is running. It will also * reset some caches when that happens. * <p> * Before 5.6, when activating this mode, the Runtime Framework stopped on low-level errors, see * {@link #handleDevError(Throwable)} but this behaviour has been removed. */ public static boolean isDevModeSet() { return isBooleanPropertyTrue(NUXEO_DEV_SYSTEM_PROP); } /** * Returns true if test mode is set. * <p> * Activating this mode, some of the code may not behave as it would in production, to ease up testing. */ public static boolean isTestModeSet() { if (testModeSet == null) { testModeSet = isBooleanPropertyTrue(NUXEO_TESTING_SYSTEM_PROP); } return testModeSet; } /** * Returns true if given property is false when compared to a boolean value. Returns false if given property in * unset. * <p> * Checks for the system properties if property is not found in the runtime properties. * * @since 5.8 */ public static boolean isBooleanPropertyFalse(String propName) { String v = getProperty(propName); if (v == null) { v = System.getProperty(propName); } if (StringUtils.isBlank(v)) { return false; } return !Boolean.parseBoolean(v); } /** * Returns true if given property is true when compared to a boolean value. * <p> * Checks for the system properties if property is not found in the runtime properties. * * @since 5.6 */ public static boolean isBooleanPropertyTrue(String propName) { String v = getProperty(propName); if (v == null) { v = System.getProperty(propName); } return Boolean.parseBoolean(v); } /** * Since 5.6, this method stops the application if property {@link #NUXEO_STRICT_RUNTIME_SYSTEM_PROP} is set to * true, and one of the following errors occurred during startup. * <ul> * <li>Component XML parse error. * <li>Contribution to an unknown extension point. * <li>Component with an unknown implementation class (the implementation entry exists in the XML descriptor but * cannot be resolved to a class). * <li>Uncatched exception on extension registration / unregistration (either in framework or user component code) * <li>Uncatched exception on component activation / deactivation (either in framework or user component code) * <li>Broken Nuxeo-Component MANIFEST entry. (i.e. the entry cannot be resolved to a resource) * </ul> * <p> * Before 5.6, this method stopped the application if development mode was enabled (i.e. org.nuxeo.dev system * property is set) but this is not the case anymore to handle a dev mode that does not stop the runtime framework * when using hot reload. * * @param t the exception or null if none */ public static void handleDevError(Throwable t) { if (isBooleanPropertyTrue(NUXEO_STRICT_RUNTIME_SYSTEM_PROP)) { System.err.println("Fatal error caught in strict " + "runtime mode => exiting."); if (t != null) { t.printStackTrace(); } System.exit(1); } else if (t != null) { log.error(t, t); } } /** * @see FileEventTracker * @param aFile The file to delete * @param aMarker the marker Object */ public static void trackFile(File aFile, Object aMarker) { FileEvent.onFile(Framework.class, aFile, aMarker).send(); } /** * Strategy is not customizable anymore. * * @deprecated * @since 6.0 * @see #trackFile(File, Object) * @see org.nuxeo.runtime.trackers.files.FileEventTracker.SafeFileDeleteStrategy * @param file The file to delete * @param marker the marker Object * @param fileDeleteStrategy ignored deprecated parameter */ @Deprecated public static void trackFile(File file, Object marker, FileDeleteStrategy fileDeleteStrategy) { trackFile(file, marker); } /** * @since 6.0 */ protected static void checkRuntimeInitialized() { if (runtime == null) { throw new IllegalStateException("Runtime not initialized"); } } public static void main(String[] args) { } /** * Creates an empty file in the framework temporary-file directory ({@code nuxeo.tmp.dir} vs {@code java.io.tmpdir} * ), using the given prefix and suffix to generate its name. * <p> * Invoking this method is equivalent to invoking * <code>{@link File#createTempFile(java.lang.String, java.lang.String, java.io.File) * File.createTempFile(prefix, suffix, Environment.getDefault().getTemp())}</code>. * <p> * The {@link #createTempFilePath(String, String, FileAttribute...)} method provides an alternative method to create * an empty file in the framework temporary-file directory. Files created by that method may have more restrictive * access permissions to files created by this method and so may be more suited to security-sensitive applications. * * @param prefix The prefix string to be used in generating the file's name; must be at least three characters long * @param suffix The suffix string to be used in generating the file's name; may be <code>null</code>, in which case * the suffix <code>".tmp"</code> will be used * @return An abstract pathname denoting a newly-created empty file * @throws IllegalArgumentException If the <code>prefix</code> argument contains fewer than three characters * @throws IOException If a file could not be created * @throws SecurityException If a security manager exists and its <code> * {@link java.lang.SecurityManager#checkWrite(java.lang.String)}</code> method does not allow a file to * be created * @since 8.1 * @see File#createTempFile(String, String, File) * @see Environment#getTemp() * @see #createTempFilePath(String, String, FileAttribute...) * @see #createTempDirectory(String, FileAttribute...) */ public static File createTempFile(String prefix, String suffix) throws IOException { try { return File.createTempFile(prefix, suffix, getTempDir()); } catch (IOException e) { throw new IOException("Could not create temp file in " + getTempDir(), e); } } /** * @return the Nuxeo temp dir returned by {@link Environment#getTemp()}. If the Environment fails to initialize, * then returns the File denoted by {@code "nuxeo.tmp.dir"} System property, or {@code "java.io.tmpdir"}. * @since 8.1 */ private static File getTempDir() { Environment env = Environment.getDefault(); File temp = env != null ? env.getTemp() : new File(System.getProperty("nuxeo.tmp.dir", System.getProperty("java.io.tmpdir"))); temp.mkdirs(); return temp; } /** * Creates an empty file in the framework temporary-file directory ({@code nuxeo.tmp.dir} vs {@code java.io.tmpdir} * ), using the given prefix and suffix to generate its name. The resulting {@code Path} is associated with the * default {@code FileSystem}. * <p> * Invoking this method is equivalent to invoking * {@link Files#createTempFile(Path, String, String, FileAttribute...) * Files.createTempFile(Environment.getDefault().getTemp().toPath(), prefix, suffix, attrs)}. * * @param prefix the prefix string to be used in generating the file's name; may be {@code null} * @param suffix the suffix string to be used in generating the file's name; may be {@code null}, in which case " * {@code .tmp}" is used * @param attrs an optional list of file attributes to set atomically when creating the file * @return the path to the newly created file that did not exist before this method was invoked * @throws IllegalArgumentException if the prefix or suffix parameters cannot be used to generate a candidate file * name * @throws UnsupportedOperationException if the array contains an attribute that cannot be set atomically when * creating the directory * @throws IOException if an I/O error occurs or the temporary-file directory does not exist * @throws SecurityException In the case of the default provider, and a security manager is installed, the * {@link SecurityManager#checkWrite(String) checkWrite} method is invoked to check write access to the * file. * @since 8.1 * @see Files#createTempFile(Path, String, String, FileAttribute...) * @see Environment#getTemp() * @see #createTempFile(String, String) */ public static Path createTempFilePath(String prefix, String suffix, FileAttribute<?>... attrs) throws IOException { try { return Files.createTempFile(getTempDir().toPath(), prefix, suffix, attrs); } catch (IOException e) { throw new IOException("Could not create temp file in " + getTempDir(), e); } } /** * Creates a new directory in the framework temporary-file directory ({@code nuxeo.tmp.dir} vs * {@code java.io.tmpdir}), using the given prefix to generate its name. The resulting {@code Path} is associated * with the default {@code FileSystem}. * <p> * Invoking this method is equivalent to invoking {@link Files#createTempDirectory(Path, String, FileAttribute...) * Files.createTempDirectory(Environment.getDefault().getTemp().toPath(), prefix, suffix, attrs)}. * * @param prefix the prefix string to be used in generating the directory's name; may be {@code null} * @param attrs an optional list of file attributes to set atomically when creating the directory * @return the path to the newly created directory that did not exist before this method was invoked * @throws IllegalArgumentException if the prefix cannot be used to generate a candidate directory name * @throws UnsupportedOperationException if the array contains an attribute that cannot be set atomically when * creating the directory * @throws IOException if an I/O error occurs or the temporary-file directory does not exist * @throws SecurityException In the case of the default provider, and a security manager is installed, the * {@link SecurityManager#checkWrite(String) checkWrite} method is invoked to check write access when * creating the directory. * @since 8.1 * @see Files#createTempDirectory(Path, String, FileAttribute...) * @see Environment#getTemp() * @see #createTempFile(String, String) */ public static Path createTempDirectory(String prefix, FileAttribute<?>... attrs) throws IOException { try { return Files.createTempDirectory(getTempDir().toPath(), prefix, attrs); } catch (IOException e) { throw new IOException("Could not create temp directory in " + getTempDir(), e); } } }