/******************************************************************************* * Copyright (c) 2003, 2011 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.osgi.service.resolver; import java.io.*; import java.util.*; import org.eclipse.osgi.internal.resolver.StateObjectFactoryImpl; import org.osgi.framework.*; /** * A factory for states and their component objects. *

* This interface is not intended to be implemented by clients. *

* @since 3.1 * @noimplement This interface is not intended to be implemented by clients. */ public interface StateObjectFactory { /** * The default object factory that can be used to create, populate and resolve * states. This is particularly useful when using the resolver outside the context * of a running Equinox framework. */ public static final StateObjectFactory defaultFactory = new StateObjectFactoryImpl(); /** * Creates an empty state. The returned state does not have an * attached resolver. * * @return the created state * @deprecated use {@link #createState(boolean) } */ public State createState(); /** * Creates an empty state with or without a resolver. * * @param resolver true if the created state should be initialized with a resolver. * @return the created state * @since 3.2 */ public State createState(boolean resolver); /** * Creates a new state that is a copy of the given state. The returned state * will contain copies of all bundle descriptions in the given state. * The user objects from the original bundle descriptions is not copied and * no data pertaining to resolution is copied. The returned state will have a * new resolver attached to it. * * @param state a state to be copied * @return the created state */ public State createState(State state); /** * Creates a bundle description from the given parameters. * * @param id id for the bundle * @param symbolicName symbolic name for the bundle (may be * null) * @param version version for the bundle (may be null) * @param location location for the bundle (may be null) * @param required version constraints for all required bundles (may be * null) * @param host version constraint specifying the host for the bundle to be * created. Should be null if the bundle is not a fragment * @param imports version constraints for all packages imported * (may be null) * @param exports package descriptions of all the exported packages * (may be null) * @param providedPackages the list of provided packages (may be null) * @param singleton whether the bundle created should be a singleton * @return the created bundle description * @deprecated use {@link #createBundleDescription(long, String, Version, String, BundleSpecification[], HostSpecification, ImportPackageSpecification[], ExportPackageDescription[], boolean, boolean, boolean, String, String[], GenericSpecification[], GenericDescription[])} */ public BundleDescription createBundleDescription(long id, String symbolicName, Version version, String location, BundleSpecification[] required, HostSpecification host, ImportPackageSpecification[] imports, ExportPackageDescription[] exports, String[] providedPackages, boolean singleton); /** * Creates a bundle description from the given parameters. * * @param id id for the bundle * @param symbolicName symbolic name for the bundle (may be * null) * @param version version for the bundle (may be null) * @param location location for the bundle (may be null) * @param required version constraints for all required bundles (may be * null) * @param host version constraint specifying the host for the bundle to be * created. Should be null if the bundle is not a fragment * @param imports version constraints for all packages imported * (may be null) * @param exports package descriptions of all the exported packages * (may be null) * @param providedPackages the list of provided packages (may be null) * @param singleton whether the bundle created should be a singleton * @param attachFragments whether the bundle allows fragments to attach * @param dynamicFragments whether the bundle allows fragments to dynamically attach * @param platformFilter the platform filter (may be null) * @param executionEnvironment the execution environment (may be null) * @param genericRequires the version constraints for all required capabilities (may be null) * @param genericCapabilities the specifications of all the capabilities of the bundle (may be null) * @return the created bundle description * @deprecated use {@link #createBundleDescription(long, String, Version, String, BundleSpecification[], HostSpecification, ImportPackageSpecification[], ExportPackageDescription[], boolean, boolean, boolean, String, String[], GenericSpecification[], GenericDescription[])} */ public BundleDescription createBundleDescription(long id, String symbolicName, Version version, String location, BundleSpecification[] required, HostSpecification host, ImportPackageSpecification[] imports, ExportPackageDescription[] exports, String[] providedPackages, boolean singleton, boolean attachFragments, boolean dynamicFragments, String platformFilter, String executionEnvironment, GenericSpecification[] genericRequires, GenericDescription[] genericCapabilities); /** * Creates a bundle description from the given parameters. * * @param id id for the bundle * @param symbolicName symbolic name for the bundle (may be null) * @param version version for the bundle (may be null) * @param location location for the bundle (may be null) * @param required version constraints for all required bundles (may be null) * @param host version constraint specifying the host for the bundle to be created. Should be null if the bundle is not a fragment * @param imports version constraints for all packages imported (may be null) * @param exports package descriptions of all the exported packages (may be null) * @param singleton whether the bundle created should be a singleton * @param attachFragments whether the bundle allows fragments to attach * @param dynamicFragments whether the bundle allows fragments to dynamically attach * @param platformFilter the platform filter (may be null) * @param executionEnvironments the execution environment (may be null) * @param genericRequires the version constraints for all required capabilities (may be null) * @param genericCapabilities the specifications of all the capabilities of the bundle (may be null) * @return the created bundle description */ public BundleDescription createBundleDescription(long id, String symbolicName, Version version, String location, BundleSpecification[] required, HostSpecification host, ImportPackageSpecification[] imports, ExportPackageDescription[] exports, boolean singleton, boolean attachFragments, boolean dynamicFragments, String platformFilter, String[] executionEnvironments, GenericSpecification[] genericRequires, GenericDescription[] genericCapabilities); /** * Creates a bundle description from the given parameters. * * @param id id for the bundle * @param symbolicName symbolic name for the bundle (may be null) * @param version version for the bundle (may be null) * @param location location for the bundle (may be null) * @param required version constraints for all required bundles (may be null) * @param host version constraint specifying the host for the bundle to be created. Should be null if the bundle is not a fragment * @param imports version constraints for all packages imported (may be null) * @param exports package descriptions of all the exported packages (may be null) * @param singleton whether the bundle created should be a singleton * @param attachFragments whether the bundle allows fragments to attach * @param dynamicFragments whether the bundle allows fragments to dynamically attach * @param platformFilter the platform filter (may be null) * @param executionEnvironments the execution environment (may be null) * @param genericRequires the version constraints for all required capabilities (may be null) * @param genericCapabilities the specifications of all the capabilities of the bundle (may be null) * @param nativeCode the native code specification of the bundle (may be null) * @return the created bundle description * @since 3.4 */ public BundleDescription createBundleDescription(long id, String symbolicName, Version version, String location, BundleSpecification[] required, HostSpecification host, ImportPackageSpecification[] imports, ExportPackageDescription[] exports, boolean singleton, boolean attachFragments, boolean dynamicFragments, String platformFilter, String[] executionEnvironments, GenericSpecification[] genericRequires, GenericDescription[] genericCapabilities, NativeCodeSpecification nativeCode); /** * Creates a bundle description from the given parameters. * * @param id id for the bundle * @param symbolicName the symbolic name of the bundle. This may include directives and/or attributes encoded using the Bundle-SymbolicName header. * @param version version for the bundle (may be null) * @param location location for the bundle (may be null) * @param required version constraints for all required bundles (may be null) * @param host version constraint specifying the host for the bundle to be created. Should be null if the bundle is not a fragment * @param imports version constraints for all packages imported (may be null) * @param exports package descriptions of all the exported packages (may be null) * @param platformFilter the platform filter (may be null) * @param executionEnvironments the execution environment (may be null) * @param genericRequires the version constraints for all required capabilities (may be null) * @param genericCapabilities the specifications of all the capabilities of the bundle (may be null) * @param nativeCode the native code specification of the bundle (may be null) * @return the created bundle description * @since 3.8 */ public BundleDescription createBundleDescription(long id, String symbolicName, Version version, String location, BundleSpecification[] required, HostSpecification host, ImportPackageSpecification[] imports, ExportPackageDescription[] exports, String platformFilter, String[] executionEnvironments, GenericSpecification[] genericRequires, GenericDescription[] genericCapabilities, NativeCodeSpecification nativeCode); /** * Returns a bundle description based on the information in the supplied manifest dictionary. * The manifest should contain String keys and String values which correspond to * proper OSGi manifest headers and values. * * @param state the state for which the description is being created * @param manifest a collection of OSGi manifest headers and values * @param location the URL location of the bundle (may be null) * @param id the id of the bundle * @return a bundle description derived from the given information * @throws BundleException if an error occurs while reading the manifest */ public BundleDescription createBundleDescription(State state, Dictionary manifest, String location, long id) throws BundleException; /** * Returns a bundle description based on the information in the supplied manifest dictionary. * The manifest should contain String keys and String values which correspond to * proper OSGi manifest headers and values. * * @param manifest a collection of OSGi manifest headers and values * @param location the URL location of the bundle (may be null) * @param id the id of the bundle * @return a bundle description derived from the given information * @throws BundleException if an error occurs while reading the manifest * @deprecated use {@link #createBundleDescription(State, Dictionary, String, long)} */ public BundleDescription createBundleDescription(Dictionary manifest, String location, long id) throws BundleException; /** * Creates a bundle description that is a copy of the given description. * The user object of the original bundle description is not copied. * * @param original the bundle description to be copied * @return the created bundle description */ public BundleDescription createBundleDescription(BundleDescription original); /** * Creates a bundle specification from the given parameters. * * @param requiredSymbolicName the symbolic name for the required bundle * @param requiredVersionRange the required version range (may be null) * @param export whether the required bundle should be re-exported * @param optional whether the constraint should be optional * @return the created bundle specification * @see VersionConstraint for information on the available match rules */ public BundleSpecification createBundleSpecification(String requiredSymbolicName, VersionRange requiredVersionRange, boolean export, boolean optional); /** * Creates a bundle specification that is a copy of the given constraint. * * @param original the constraint to be copied * @return the created bundle specification */ public BundleSpecification createBundleSpecification(BundleSpecification original); /** * Creates bundle specifications from the given declaration. The declaration uses * the bundle manifest syntax for the Require-Bundle header. * @param declaration a string declaring bundle specifications * @return the bundle specifications * @since 3.8 */ public List createBundleSpecifications(String declaration); /** * Creates a host specification from the given parameters. * * @param hostSymbolicName the symbolic name for the host bundle * @param hostVersionRange the version range for the host bundle (may be null) * @return the created host specification * @see VersionConstraint for information on the available match rules */ public HostSpecification createHostSpecification(String hostSymbolicName, VersionRange hostVersionRange); /** * Creates host specifications from the given declaration. The declaration uses * the bundle manifest syntax for the Fragment-Host header. * @param declaration a string declaring host specifications * @return the host specifications * @since 3.8 */ public List createHostSpecifications(String declaration); /** * Creates a host specification that is a copy of the given constraint. * * @param original the constraint to be copied * @return the created host specification */ public HostSpecification createHostSpecification(HostSpecification original); /** * Creates an import package specification from the given parameters. * * @param packageName the package name * @param versionRange the package versionRange (may be null). * @param bundleSymbolicName the Bundle-SymbolicName of the bundle that must export the package (may be null) * @param bundleVersionRange the bundle versionRange (may be null). * @param directives the directives for this package (may be null) * @param attributes the arbitrary attributes for the package import (may be null) * @param importer the importing bundle (may be null) * @return the created package specification */ public ImportPackageSpecification createImportPackageSpecification(String packageName, VersionRange versionRange, String bundleSymbolicName, VersionRange bundleVersionRange, Map directives, Map attributes, BundleDescription importer); /** * Creates an import package specification that is a copy of the given import package * @param original the import package to be copied * @return the created package specification */ public ImportPackageSpecification createImportPackageSpecification(ImportPackageSpecification original); /** * Creates an import package specifications from the given declaration. The declaration uses * the bundle manifest syntax for the Import-Package header. * @param declaration a string declaring import package specifications * @return the import package specifications * @since 3.8 */ public List createImportPackageSpecifications(String declaration); /** * Used by the Resolver to dynamically create ExportPackageDescription objects during the resolution process. * The Resolver needs to create ExportPackageDescriptions dynamically for a host when a fragment. * exports a package

* * @param packageName the package name * @param version the version of the package (may be null) * @param directives the directives for the package (may be null) * @param attributes the attributes for the package (may be null) * @param root whether the package is a root package * @param exporter the exporter of the package (may be null) * @return the created package */ public ExportPackageDescription createExportPackageDescription(String packageName, Version version, Map directives, Map attributes, boolean root, BundleDescription exporter); /** * Creates a generic description from the given parameters * @param name the name of the generic description * @param type the type of the generic description (may be null) * @param version the version of the generic description (may be null) * @param attributes the attributes for the generic description (may be null) * @return the created generic description * @deprecated use {@link #createGenericDescription(String, String, Version, Map)} */ public GenericDescription createGenericDescription(String name, String type, Version version, Map attributes); /** * Creates a generic description from the given parameters * @param type the type of the generic description (may be null) * @param attributes the attributes for the generic description (may be null) * @param directives the directives for the generic description (may be null) * @param supplier the supplier of the generic description (may be null) * @return the created generic description * @since 3.7 */ public GenericDescription createGenericDescription(String type, Map attributes, Map directives, BundleDescription supplier); /** * Creates generic descriptions from the given declaration. The declaration uses * the bundle manifest syntax for the Provide-Capability header. * @param declaration a string declaring generic descriptions * @return the generic descriptions * @since 3.8 */ public List createGenericDescriptions(String declaration); /** * Creates a generic specification from the given parameters * @param name the name of the generic specification * @param type the type of the generic specification (may be null) * @param matchingFilter the matching filter (may be null) * @param optional whether the specification is optional * @param multiple whether the specification allows for multiple suppliers * @return the created generic specification * @throws InvalidSyntaxException if the matching filter is invalid */ public GenericSpecification createGenericSpecification(String name, String type, String matchingFilter, boolean optional, boolean multiple) throws InvalidSyntaxException; /** * Creates generic specifications from the given declaration. The declaration uses * the bundle manifest syntax for the Require-Capability header. * @param declaration a string declaring generic specifications * @return the generic specifications * @since 3.8 */ public List createGenericSpecifications(String declaration); /** * Creates a native code specification from the given parameters * @param nativeCodeDescriptions the native code descriptors * @param optional whether the specification is optional * @return the created native code specification * @since 3.4 */ public NativeCodeSpecification createNativeCodeSpecification(NativeCodeDescription[] nativeCodeDescriptions, boolean optional); /** * Creates a native code description from the given parameters * @param nativePaths the native code paths (may be null) * @param processors the supported processors (may be null) * @param osNames the supported operating system names (may be null) * @param osVersions the supported operating system version ranges (may be null) * @param languages the supported languages (may be null) * @param filter the selection filter (may be null) * @return the created native code description * @throws InvalidSyntaxException if the selection filter is invalid * @since 3.4 */ public NativeCodeDescription createNativeCodeDescription(String[] nativePaths, String[] processors, String[] osNames, VersionRange[] osVersions, String[] languages, String filter) throws InvalidSyntaxException; /** * Creates an export package specification that is a copy of the given constraint * @param original the export package to be copied * @return the created package */ public ExportPackageDescription createExportPackageDescription(ExportPackageDescription original); /** * Creates export package descriptions from the given declaration. The declaration uses * the bundle manifest syntax for the Export-Package header. * @param declaration a string declaring export package descriptions * @return the export package descriptions * @since 3.8 */ public List createExportPackageDescriptions(String declaration); /** * Persists the given state in the given output stream. Closes the stream. * * @param state the state to be written * @param stream the stream where to write the state to * @throws IOException if an IOException happens while writing the state to * the stream * @throws IllegalArgumentException if the state provided was not created by * this factory * @deprecated use {@link #writeState(State, File)} instead * @since 3.1 */ public void writeState(State state, OutputStream stream) throws IOException; /** * Persists the given state in the given output stream. Closes the stream. * * @param state the state to be written * @param stream the stream where to write the state to * @throws IOException if an IOException happens while writing the state to * the stream * @throws IllegalArgumentException if the state provided was not created by * this factory * @deprecated use {@link #writeState(State, File)} instead * @see #writeState(State, OutputStream) */ public void writeState(State state, DataOutputStream stream) throws IOException; /** * Persists the given state in the given directory. * * @param state the state to be written * @param stateDirectory the directory where to write the state to * @throws IOException if an IOException happens while writing the state to * the stream * @throws IllegalArgumentException if the state provided was not created by * this factory */ public void writeState(State state, File stateDirectory) throws IOException; /** * Reads a persisted state from the given stream. Closes the stream. * * @param stream the stream where to read the state from * @return the state read * @throws IOException if an IOException happens while reading the state from * the stream * @deprecated use {@link #readState(File)} instead * @since 3.1 */ public State readState(InputStream stream) throws IOException; /** * Reads a persisted state from the given stream. Closes the stream. * * @param stream the stream where to read the state from * @return the state read * @throws IOException if an IOException happens while reading the state from * the stream * @deprecated use {@link #readState(File)} instead * @see #readState(InputStream) */ public State readState(DataInputStream stream) throws IOException; /** * Reads a persisted state from the given directory. * * @param stateDirectory the directory where to read the state from * @return the state read * @throws IOException if an IOException happens while reading the state from * the stream */ public State readState(File stateDirectory) throws IOException; }