| /******************************************************************************* |
| * Copyright (c) 2007, 2008 IBM Corporation and others. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v1.0 |
| * which accompanies this distribution, and is available at |
| * http://www.eclipse.org/legal/epl-v10.html |
| * |
| * Contributors: |
| * IBM Corporation - initial API and implementation |
| *******************************************************************************/ |
| package org.eclipse.equinox.internal.provisional.frameworkadmin; |
| |
| import java.io.File; |
| import java.io.IOException; |
| |
| /** |
| * The implementation of this API will be registered to the service |
| * registry as an OSGi service. |
| * |
| * ***************************************************************** |
| * 1. For developers who implement bundles that register this service. |
| * |
| * Upon registration, the following service properties must be set to allow clients to |
| * search the FrameworkAdmin object, which will create BundlesState / ConfigData / LauncherData objects. |
| * |
| * {@link FrameworkAdmin#SERVICE_PROP_KEY_FW_NAME}: String; name of the framework |
| * {@link FrameworkAdmin#SERVICE_PROP_KEY_FW_VERSION}: String; version of the framework |
| * {@link FrameworkAdmin#SERVICE_PROP_KEY_LAUNCHER_NAME}: String; name of the launcher |
| * {@link FrameworkAdmin#SERVICE_PROP_KEY_LAUNCHER_VERSION}: String; version of the launcher |
| * |
| * Bundles that register this service will check if the currently running system can be manipulated by |
| * this FrameworkAdmin. If yes and this implementation can create an initialized Manipulator object |
| * according to the running framework and launcher, add the service property keyed by |
| * |
| * {@link FrameworkAdmin#SERVICE_PROP_KEY_RUNNING_SYSTEM_FLAG}: String; if "true", |
| * the service that will be returned by getRunningManipulator() is fully initialized to |
| * represent the state of the running system. |
| * |
| * It is recommended to implement Manipulator objects created by calling methods of this interface |
| * so that they cannot be used after this service is unregistered. |
| * |
| * ***************************************************************** |
| * 2. For developers who implement client bundles that use this service. |
| * |
| * A client of this service can obtain a Manipulator object by calling the {@link #getManipulator()} method. |
| * |
| * A client can search among services registered in a service registry to find the |
| * desired FrameworkAdmin implementation that matches the desired framework |
| * type, framework version, launcher type, and launcher version. |
| * |
| * In order for a client bundle to manipulate the {@link Manipulator} object |
| * of the running framework and launcher, the service filter (FrameworkAdmin#SERVICE_PROP_KEY_RUNNING_FW_FLAG=true) |
| * should be used. |
| * |
| * As with all OSGi services, the client bundle should track this service state. |
| * If the service is unregistered, it should stop using any of the objects obtained from this service and |
| * release them. If it continues to use them, {@link FrameworkAdminRuntimeException} might |
| * be thrown. |
| * |
| * ***************************************************************** |
| * In addition, FrameworkAdminFactory will create this object. This is used by Java programs. |
| * |
| * @see FrameworkAdminFactory |
| * |
| */ |
| public interface FrameworkAdmin { |
| |
| String SERVICE_PROP_KEY_FW_NAME = "org.eclipse.equinox.frameworkhandler.framework.name"; |
| String SERVICE_PROP_KEY_FW_VERSION = "org.eclipse.equinox.frameworkhandler.framework.version"; |
| |
| String SERVICE_PROP_KEY_LAUNCHER_NAME = "org.eclipse.equinox.frameworkhandler.launcher.name"; |
| String SERVICE_PROP_KEY_LAUNCHER_VERSION = "org.eclipse.equinox.frameworkhandler.launcher.version"; |
| String SERVICE_PROP_KEY_RUNNING_SYSTEM_FLAG = "org.eclipse.equinox.frameworkhandler.runningfwflag"; |
| |
| /** |
| * Create new instance of {@link Manipulator} and return it. |
| * |
| * @return new instance of Manipulator. |
| */ |
| public Manipulator getManipulator(); |
| |
| /** |
| * Create new instance of {@link Manipulator} for running system |
| * and return it. The instance must be initialized fully according to the |
| * running environment. If this implementation cannot provide it, return null. |
| * |
| * @return new instance of Manipulator. |
| */ |
| public Manipulator getRunningManipulator(); |
| |
| /** |
| * Launch a framework instance under the specified current working directory. |
| * |
| * @param manipulator {@link Manipulator} object to be launched. |
| * @param cwd current working directory to be used for launching. |
| * @return process |
| * @throws IllegalArgumentException if specified arguments are null. |
| * @throws IOException if any error relate with IO occurs |
| * @throws FrameworkAdminRuntimeException if the FrameworkAdmin service object |
| * that created the specified Manipulator object is unregistered. |
| */ |
| public Process launch(Manipulator manipulator, File cwd) throws IllegalArgumentException, IOException, FrameworkAdminRuntimeException; |
| |
| /** |
| * |
| * @return true if this object is active. false otherwise. |
| */ |
| public boolean isActive(); |
| } |