| /******************************************************************************* |
| * 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; |
| |
| import org.eclipse.equinox.internal.provisional.configuratormanipulator.ConfiguratorManipulator; |
| |
| /** |
| * A manipulator is used to query and modify the state of a framework instance. |
| * A manipulator instance is obtained by calling {@link FrameworkAdmin#getManipulator()}. |
| * |
| * The typical use-cases of this interface: |
| * |
| * Usecase 1: set parameters, check the expected state, save them into configuration files, and launch. |
| * A. create a {@link Manipulator} object from a {@link FrameworkAdmin}. |
| * B. set parameters to the {@link Manipulator} object. |
| * C. getExpectedState() and check what bundle state will be realized. |
| * If it is not same as you desire, repeat B and C until it becomes as you desire. |
| * D. save parameters into configuration files by {@link Manipulator#save(boolean)}. |
| * E. launch the framework by {@link FrameworkAdmin#launch(Manipulator, File)}. |
| * |
| * Usecase 2: set parameters required for loading, load parameters from configuration files, |
| * check the expected state, and launch. |
| * A. create a {@link Manipulator} object from a {@link FrameworkAdmin}. |
| * B. set parameters about launcher or framework configuration file to the {@link Manipulator} object. |
| * C. load parameters from configuration files by {@link Manipulator#load()}; |
| * D. getExpectedState() and check what bundle state will be realized. |
| * E. launch the framework by {@link FrameworkAdmin#launch(Manipulator, File)}. |
| * @see FrameworkAdmin |
| * @see ConfigData |
| * @see LauncherData |
| */ |
| public interface Manipulator { |
| |
| /** |
| * Return the newly created BundldsState object, |
| * according to the parameters set to this object "in memory". |
| * |
| * None of launcher config file, framework config file and configurator config file |
| * will be read by this method. However, the framework persistent data location should be |
| * taken into consideration. In other words, this method will return |
| * the expected {@link BundlesState} object assuming that the current parameters were saved and |
| * {@link FrameworkAdmin#launch(Manipulator, File)} with an argument of this object |
| * were called. (It would read the framework persistent data location if required). |
| * |
| * This method should not modify the parameters in this {@link Manipulator} object. |
| * |
| * @return framework bundle state object created according to he current parameters set. |
| * @throws FrameworkAdminRuntimeException - If the {@link FrameworkAdmin} service created this object is unregistered or this implementation doesn't support this method. |
| */ |
| BundlesState getBundlesState() throws FrameworkAdminRuntimeException; |
| |
| /** |
| * The reference of {@link ConfigData} object representing configuration information related with framework settings will be returned. |
| * Remind that manipulating returned object will affect this Manipulator behavior. |
| * |
| * @return ConfigData object representing configuration information related with framework setting |
| * @throws FrameworkAdminRuntimeException - If the {@link FrameworkAdmin} service created this object is unregistered or this implementation doesn't support this method. |
| * @see ConfigData |
| */ |
| ConfigData getConfigData() throws FrameworkAdminRuntimeException; |
| |
| /** |
| * Return the expected BundleInfo array representing state of bundles, |
| * according to the parameters set to this object "in memory". |
| * |
| * None of launcher config file, framework config file and configurator config file |
| * will be read by this method. However, the framework persistent data location should be |
| * taken into consideration. In other words, this method will return |
| * the expected bundles state assuming that the current parameters were saved and |
| * {@link FrameworkAdmin#launch(Manipulator, File)} with an argument of this object |
| * were called. (It would read the framework persistent data location if required). |
| * |
| * Returned BundleInfos must have resolved flag set. |
| * This method should not modify the parameters in this {@link Manipulator} object. |
| * |
| * cf. getConfigData().getBundles() will return array of BundleInfo too. |
| * However the resolved flag of returned BundleInfos might not be reliable. |
| * |
| * This method is equivalent to calling getBundlesState().getExpectedState(). |
| * |
| * @return array of BundleInfo representing expected state of all bundles installed. |
| * @throws IllegalArgumentException - If either of fwJar or cwd doesn't exist. |
| * @throws IOException - If reading fw configuration file or reading persistently recorded information |
| * of fw fails. |
| * @throws FrameworkAdminRuntimeException - If the {@link FrameworkAdmin} service created this object is unregistered or this implementation doesn't support this method. |
| */ |
| BundleInfo[] getExpectedState() throws IllegalStateException, IOException, FrameworkAdminRuntimeException; |
| |
| /** |
| * The reference of {@link LauncherData} object representing configuration information |
| * related with launcher settings will be returned. |
| * Remember that manipulating returned object will affect this Manipulator object behavior. |
| * |
| * @return LauncherData object representing configuration information related with launcher setting |
| * @throws FrameworkAdminRuntimeException - If the ManipulatorAdmin service created this object is unregistered or this implementation doesn't support this method. |
| * @see LauncherData |
| */ |
| LauncherData getLauncherData() throws FrameworkAdminRuntimeException; |
| |
| /** |
| * Return timestamp of configurations which will be loaded by load() method |
| * according to the parameters set to this manipulator in long value. |
| * |
| * This method will check last modified time of all launcher configuration file, framework configuration file, |
| * and framework persistent storage according to the parameters set. |
| * @return |
| */ |
| long getTimeStamp(); |
| |
| /** |
| * Initialize all information that this object keeps at that time. |
| */ |
| void initialize(); |
| |
| /** |
| * load configs from appropriate config files, |
| * including launcher config file, fw config file, and configurator config files, |
| * whose locations are determined by the current setting. In addition, |
| * the fw persistent data location should be taken into consideration. |
| * |
| * The following procedure contains the matters of implementation detail. |
| * However, it is an example how it works. |
| * |
| * 1. if launcher object is set, corresponding launcher config file will be read. |
| * According to the information retrieved, setting of this object will be updated. |
| * including fw config file. |
| * |
| * 2. If fw config file is not specified, IllegalStateException will be thrown. |
| * Otherwise, the information will be retrieved from the fw config file. |
| * |
| * 3. If any ConfiguratorBundle is included in the bundle list, |
| * read appropriate configurator config file by |
| * {@link ConfiguratorManipulator#updateBundles(Manipulator)}, |
| * which will update the parameter about installed bundles in its |
| * {@link Manipulator#getConfigData()} object. |
| * |
| * Most old parameters will be updated by this method call. |
| * |
| * @throws IOException - If reading info from configuration files fails. |
| * @throws IllegalStateException - If config files cannot be determined. |
| * @throws FrameworkAdminRuntimeException - If the {@link FrameworkAdmin} service created this object is unregistered or this implementation doesn't support this method. |
| */ |
| void load() throws IllegalStateException, IOException, FrameworkAdminRuntimeException; |
| |
| /** |
| * Save parameters that this object keeps at that time into appropriate configuration files, |
| * which include launcher configuration file, framework configuration file, and configurator configuration files |
| * (if required and implementation of this object supports), according to the current setting and situation. |
| * |
| * The following procedure contains the matters of implementation detail. |
| * However, it is an example how it works. |
| * |
| * 1. if a launcher file is set, |
| * the parameters to be saved into a LauncherConfigFile will be saved into the default LauncherConfigFile |
| * that is determined by the location of the launcher file. |
| * |
| * |
| * 2. if there are any {@link ConfiguratorManipulator} objects available whose corresponding ConfiguratorBundle |
| * is set to be started, choose the ConfiguratorBudnle that starts the first among them and go to next step. |
| * Otherwise, save the BundleInfo[] set to this object into a FwConfigFile that is determined |
| * by the parameters set. |
| * |
| * 3. call {@link ConfiguratorManipulator#save(Manipulator, boolean)} of |
| * the ConfiguratorManipulator that can manipulate the chosen ConfiguratorBudnle. |
| * This method will save configurations for ConfiguratorBundle to read appropriately |
| * and return BundleInfo[] to be saved in the FwConfigFile, which is determined by the parameters set. |
| * |
| * 4. Save the returned BundleInfo[] in the FwConfigFile, which is determined by the parameters set. |
| * |
| * @param backup - if true, keep old file by renaming if exists. |
| * @throws IOException - If writing info into configuration files fails. |
| * @throws FrameworkAdminRuntimeException - If the {@link FrameworkAdmin} service created this object is unregistered or this implementation doesn't support this method. |
| */ |
| void save(boolean backup) throws IOException, FrameworkAdminRuntimeException; |
| |
| /** |
| * Copy all information the specified {@link ConfigData} contains into this object. |
| * All of old settings will be initialized and replaced. |
| * |
| * @param configData fw config data to be set to this object. |
| */ |
| void setConfigData(ConfigData configData); |
| |
| /** |
| * Copy all information the specified {@link LauncherData} contains into this object. |
| * All of old settings will be initialized and replaced. |
| * |
| * @param launcherData launcher config data to be set to this object. |
| */ |
| void setLauncherData(LauncherData launcherData); |
| } |