StateObjectFactory


1   /*******************************************************************************
2    * Copyright (c) 2003, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    * 
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.osgi.service.resolver;
12  
13  import java.io.*;
14  import java.util.Dictionary  ;
15  import java.util.Map  ;
16  import org.eclipse.osgi.internal.resolver.StateObjectFactoryImpl;
17  import org.osgi.framework.*;
18  
19  /**
20   * A factory for states and their component objects.  
21   * <p>
22   * Clients may implement this interface.
23   * </p>
24   * @since 3.1
25   */
26  public interface StateObjectFactory {
27  
28      /**
29       * The default object factory that can be used to create, populate and resolve
30       * states.  This is particularly useful when using the resolver outside the context
31       * of a running Equinox framework.
32       */
33      public static final StateObjectFactory defaultFactory = new StateObjectFactoryImpl();
34  
35      /**
36       * Creates an empty state. The returned state does not have an 
37       * attached resolver.
38       * 
39       * @return the created state
40       * @deprecated use {@link #createState(boolean) }
41       */
42      public State createState();
43  
44      /**
45       * Creates an empty state with or without a resolver.
46       * 
47       * @param createResolver true if the created state should be initialized with a resolver.
48       * @return the created state
49       * @since 3.2
50       */
51      public State createState(boolean resolver);
52  
53      /**
54       * Creates a new state that is a copy of the given state. The returned state 
55       * will contain copies of all bundle descriptions in the given state. No data 
56       * pertaining to resolution is copied.
57       *  
58       * @param state a state to be copied
59       * @return the created state
60       */
61      public State createState(State state);
62  
63      /**
64       * Creates a bundle description from the given parameters.
65       * 
66       * @param id id for the bundle 
67       * @param symbolicName symbolic name for the bundle (may be 
68       * <code>null</code>) 
69       * @param version version for the bundle (may be <code>null</code>)
70       * @param location location for the bundle (may be <code>null</code>)
71       * @param required version constraints for all required bundles (may be 
72       * <code>null</code>)
73       * @param host version constraint specifying the host for the bundle to be  
74       * created. Should be <code>null</code> if the bundle is not a fragment
75       * @param imports version constraints for all packages imported 
76       * (may be <code>null</code>)
77       * @param exports package descriptions of all the exported packages
78       * (may be <code>null</code>)
79       * @param providedPackages the list of provided packages (may be <code>null</code>) 
80       * @param singleton whether the bundle created should be a singleton
81       * @return the created bundle description
82       * @deprecated use {@link #createBundleDescription(long, String, Version, String, BundleSpecification[], HostSpecification, ImportPackageSpecification[], ExportPackageDescription[], boolean, boolean, boolean, String, String[], GenericSpecification[], GenericDescription[])}
83       */
84      public BundleDescription createBundleDescription(long id, String   symbolicName, Version version, String   location, BundleSpecification[] required, HostSpecification host, ImportPackageSpecification[] imports, ExportPackageDescription[] exports, String  [] providedPackages, boolean singleton);
85  
86      /**
87       * Creates a bundle description from the given parameters.
88       * 
89       * @param id id for the bundle 
90       * @param symbolicName symbolic name for the bundle (may be 
91       * <code>null</code>) 
92       * @param version version for the bundle (may be <code>null</code>)
93       * @param location location for the bundle (may be <code>null</code>)
94       * @param required version constraints for all required bundles (may be 
95       * <code>null</code>)
96       * @param host version constraint specifying the host for the bundle to be  
97       * created. Should be <code>null</code> if the bundle is not a fragment
98       * @param imports version constraints for all packages imported 
99       * (may be <code>null</code>)
100      * @param exports package descriptions of all the exported packages
101      * (may be <code>null</code>)
102      * @param providedPackages the list of provided packages (may be <code>null</code>) 
103      * @param singleton whether the bundle created should be a singleton
104      * @param attachFragments whether the bundle allows fragments to attach
105      * @param dynamicFragments whether the bundle allows fragments to dynamically attach
106      * @param platformFilter the platform filter (may be <code>null</code>)
107      * @param executionEnvironment the execution environment (may be <code>null</code>)
108      * @param genericRequires the version constraints for all required capabilities (may be <code>null</code>)
109      * @param genericCapabilities the specifications of all the capabilities of the bundle (may be <code>null</code>)
110      * @return the created bundle description
111      * @deprecated use {@link #createBundleDescription(long, String, Version, String, BundleSpecification[], HostSpecification, ImportPackageSpecification[], ExportPackageDescription[], boolean, boolean, boolean, String, String[], GenericSpecification[], GenericDescription[])}
112      */
113     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);
114 
115     /**
116      * Creates a bundle description from the given parameters.
117      * 
118      * @param id id for the bundle 
119      * @param symbolicName symbolic name for the bundle (may be  <code>null</code>) 
120      * @param version version for the bundle (may be <code>null</code>)
121      * @param location location for the bundle (may be <code>null</code>)
122      * @param required version constraints for all required bundles (may be  <code>null</code>)
123      * @param host version constraint specifying the host for the bundle to be created. Should be <code>null</code> if the bundle is not a fragment
124      * @param imports version constraints for all packages imported  (may be <code>null</code>)
125      * @param exports package descriptions of all the exported packages (may be <code>null</code>)
126      * @param singleton whether the bundle created should be a singleton
127      * @param attachFragments whether the bundle allows fragments to attach
128      * @param dynamicFragments whether the bundle allows fragments to dynamically attach
129      * @param platformFilter the platform filter (may be <code>null</code>)
130      * @param executionEnvironments the execution environment (may be <code>null</code>)
131      * @param genericRequires the version constraints for all required capabilities (may be <code>null</code>)
132      * @param genericCapabilities the specifications of all the capabilities of the bundle (may be <code>null</code>)
133      * @return the created bundle description
134      */
135     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);
136 
137 
138     /**
139      * Returns a bundle description based on the information in the supplied manifest dictionary.
140      * The manifest should contain String keys and String values which correspond to 
141      * proper OSGi manifest headers and values.
142      * 
143      * @param state the state for which the description is being created
144      * @param manifest a collection of OSGi manifest headers and values
145      * @param location the URL location of the bundle (may be <code>null</code>)
146      * @param id the id of the bundle
147      * @return a bundle description derived from the given information
148      * @throws BundleException if an error occurs while reading the manifest 
149      */
150     public BundleDescription createBundleDescription(State state, Dictionary   manifest, String   location, long id) throws BundleException;
151 
152     /**
153      * Returns a bundle description based on the information in the supplied manifest dictionary.
154      * The manifest should contain String keys and String values which correspond to 
155      * proper OSGi manifest headers and values.
156      * 
157      * @param manifest a collection of OSGi manifest headers and values
158      * @param location the URL location of the bundle (may be <code>null</code>)
159      * @param id the id of the bundle
160      * @return a bundle description derived from the given information
161      * @throws BundleException if an error occurs while reading the manifest 
162      * @deprecated use {@link #createBundleDescription(State, Dictionary, String, long)}
163      */
164     public BundleDescription createBundleDescription(Dictionary   manifest, String   location, long id) throws BundleException;
165 
166     /**
167      * Creates a bundle description that is a copy of the given description.
168      * 
169      * @param original the bundle description to be copied
170      * @return the created bundle description
171      */
172     public BundleDescription createBundleDescription(BundleDescription original);
173 
174     /**
175      * Creates a bundle specification from the given parameters.
176      * 
177      * @param requiredSymbolicName the symbolic name for the required bundle
178      * @param requiredVersionRange the required version range (may be <code>null</code>)
179      * @param export whether the required bundle should be re-exported 
180      * @param optional whether the constraint should be optional
181      * @return the created bundle specification
182      * @see VersionConstraint for information on the available match rules
183      */
184     public BundleSpecification createBundleSpecification(String   requiredSymbolicName, VersionRange requiredVersionRange, boolean export, boolean optional);
185 
186     /**
187      * Creates a bundle specification that is a copy of the given constraint.
188      *  
189      * @param original the constraint to be copied
190      * @return the created bundle specification
191      */
192     public BundleSpecification createBundleSpecification(BundleSpecification original);
193 
194     /**
195      * Creates a host specification from the given parameters.
196      *  
197      * @param hostSymbolicName the symbolic name for the host bundle
198      * @param hostVersionRange the version range for the host bundle (may be <code>null</code>)
199      * @return the created host specification
200      * @see VersionConstraint for information on the available match rules 
201      */
202     public HostSpecification createHostSpecification(String   hostSymbolicName, VersionRange hostVersionRange);
203 
204     /**
205      * Creates a host specification that is a copy of the given constraint.
206      * 
207      * @param original the constraint to be copied
208      * @return the created host specification
209      */
210     public HostSpecification createHostSpecification(HostSpecification original);
211 
212     /**
213      * Creates an import package specification from the given parameters.
214      *  
215      * @param packageName the package name
216      * @param versionRange the package versionRange (may be <code>null</code>).
217      * @param bundleSymbolicName the Bundle-SymbolicName of the bundle that must export the package (may be <code>null</code>)
218      * @param bundleVersionRange the bundle versionRange (may be <code>null</code>).
219      * @param directives the directives for this package (may be <code>null</code>)
220      * @param attributes the arbitrary attributes for the package import (may be <code>null</code>)
221      * @param importer the importing bundle (may be <code>null</code>)
222      * @return the created package specification
223      */
224     public ImportPackageSpecification createImportPackageSpecification(String   packageName, VersionRange versionRange, String   bundleSymbolicName, VersionRange bundleVersionRange, Map   directives, Map   attributes, BundleDescription importer);
225 
226     /**
227      * Creates an import package specification that is a copy of the given import package
228      * @param original the import package to be copied
229      * @return the created package specification 
230      */
231     public ImportPackageSpecification createImportPackageSpecification(ImportPackageSpecification original);
232 
233     /**
234      * Used by the Resolver to dynamically create ExportPackageDescription objects during the resolution process.
235      * The Resolver needs to create ExportPackageDescriptions dynamally for a host when a fragment.
236      * exports a package<p>
237      * 
238      * @param packageName the package name
239      * @param version the version of the package (may be <code>null</code>)
240      * @param directives the directives for the package (may be <code>null</code>)
241      * @param attributes the attributes for the package (may be <code>null</code>)
242      * @param root whether the package is a root package
243      * @param exporter the exporter of the package (may be <code>null</code>)
244      * @return the created package
245      */
246     public ExportPackageDescription createExportPackageDescription(String   packageName, Version version, Map   directives, Map   attributes, boolean root, BundleDescription exporter);
247 
248     /**
249      * Creates a generic description from the given parameters
250      * @param name the name of the generic description
251      * @param type the type of the generic description (may be <code>null</code>)
252      * @param version the version of the generic description (may be <code>null</code>)
253      * @param attributes the attributes for the generic description (may be <code>null</code>)
254      * @return the created generic description
255      */
256     public GenericDescription createGenericDescription(String   name, String   type, Version version, Map   attributes);
257 
258     /**
259      * Creates a generic specification from the given parameters
260      * @param name the name of the generic specification
261      * @param type the type of the generic specification (may be <code>null</code>)
262      * @param matchingFilter the matching filter (may be <code>null</code>)
263      * @param optional whether the specification is optional
264      * @param multiple whether the specification allows for multiple suppliers
265      * @return the created generic specification
266      * @throws InvalidSyntaxException if the matching filter is invalid
267      */
268     public GenericSpecification createGenericSpecification(String   name, String   type, String   matchingFilter, boolean optional, boolean multiple) throws InvalidSyntaxException;
269 
270     /**
271      * Creates an import package specification that is a copy of the given constraint
272      * @param original the export package to be copied
273      * @return the created package
274      */
275     public ExportPackageDescription createExportPackageDescription(ExportPackageDescription original);
276 
277     /**
278      * Persists the given state in the given output stream. Closes the stream.
279      * 
280      * @param state the state to be written
281      * @param stream the stream where to write the state to
282      * @throws IOException if an IOException happens while writing the state to 
283      * the stream
284      * @throws IllegalArgumentException if the state provided was not created by 
285      * this factory
286      * @deprecated use {@link #writeState(State, File)} instead
287      * @since 3.1
288      */
289     public void writeState(State state, OutputStream stream) throws IOException;
290 
291     /**
292      * Persists the given state in the given output stream. Closes the stream.
293      * 
294      * @param state the state to be written
295      * @param stream the stream where to write the state to
296      * @throws IOException if an IOException happens while writing the state to 
297      * the stream
298      * @throws IllegalArgumentException if the state provided was not created by 
299      * this factory
300      * @deprecated use {@link #writeState(State, File)} instead
301      * @see #writeState(State, OutputStream)
302      */
303     public void writeState(State state, DataOutputStream stream) throws IOException;
304 
305     /**
306      * Persists the given state in the given directory.
307      * 
308      * @param state the state to be written
309      * @param stateDirectory the directory where to write the state to
310      * @throws IOException if an IOException happens while writing the state to 
311      * the stream
312      * @throws IllegalArgumentException if the state provided was not created by 
313      * this factory
314      */
315     public void writeState(State state, File stateDirectory) throws IOException;
316 
317     /**
318      * Reads a persisted state from the given stream. Closes the stream.
319      * 
320      * @param stream the stream where to read the state from
321      * @return the state read
322      * @throws IOException if an IOException happens while reading the state from 
323      * the stream
324      * @deprecated use {@link #readState(File)} instead
325      * @since 3.1
326      */
327     public State readState(InputStream stream) throws IOException;
328 
329     /**
330      * Reads a persisted state from the given stream. Closes the stream.
331      * 
332      * @param stream the stream where to read the state from
333      * @return the state read
334      * @throws IOException if an IOException happens while reading the state from 
335      * the stream
336      * @deprecated use {@link #readState(File)} instead
337      * @see #readState(InputStream)
338      */
339     public State readState(DataInputStream stream) throws IOException;
340 
341     /**
342      * Reads a persisted state from the given directory.
343      * 
344      * @param stateDirectory the directory where to read the state from
345      * @return the state read
346      * @throws IOException if an IOException happens while reading the state from 
347      * the stream
348      */
349     public State readState(File stateDirectory) throws IOException;
350 
351 }
352
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags