RegistryFactory


1   /*******************************************************************************
2    * Copyright (c) 2005, 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.core.runtime;
12  
13  import java.io.File  ;
14  import org.eclipse.core.internal.registry.*;
15  import org.eclipse.core.internal.registry.osgi.RegistryStrategyOSGI;
16  import org.eclipse.core.runtime.spi.*;
17  
18  /**
19   * Use this class to create or obtain an extension registry.
20   * <p>
21   * The following methods can be used without OSGi running:
22   * </p><p><ul>
23   * <li>{@link #createRegistry(RegistryStrategy, Object, Object)}</li>
24   * <li>{@link #getRegistry()}</li>
25   * <li>{@link #setDefaultRegistryProvider(IRegistryProvider)}</li>
26   * </ul></p><p>
27   * This class is not intended to be subclassed or instantiated.
28   * </p>
29   * @since org.eclipse.equinox.registry 3.2
30   */
31  public final class RegistryFactory {
32  
33      /**
34       * Creates a new extension registry based on the given set of parameters.
35       * <p>
36       * The strategy is an optional collection of methods that supply additional registry 
37       * functionality. Users may pass in <code>null</code> for the strategy if default 
38       * behavior is sufficient.
39       * </p><p>
40       * The master token is stored by the registry and later used as an identifier of callers 
41       * who are allowed full control over the registry functionality. Users may pass in 
42       * <code>null</code> as a master token.
43       * </p><p>
44       * The user token is stored by the registry and later used as an identifier of callers
45       * who are allowed to control registry at the user level. For instance, users attempting to 
46       * modify dynamic contributions to the registry have to use the user token. Users may pass 
47       * in <code>null</code> as a user token.
48       * </p>
49       * @param strategy registry strategy or <code>null</code>
50       * @param masterToken the token used for master control of the registry or <code>null</code>
51       * @param userToken the token used for user control of the registry or <code>null</code>
52       * @return the new extension registry
53       */
54      public static IExtensionRegistry createRegistry(RegistryStrategy strategy, Object   masterToken, Object   userToken) {
55          return new ExtensionRegistry(strategy, masterToken, userToken);
56      }
57  
58      /**
59       * Returns the default extension registry specified by the registry provider.
60       * May return <code>null</code> if the provider has not been set or if the 
61       * registry has not been created.
62       * 
63       * @return existing extension registry or <code>null</code>
64       */
65      public static IExtensionRegistry getRegistry() {
66          IRegistryProvider defaultRegistryProvider = RegistryProviderFactory.getDefault();
67          if (defaultRegistryProvider == null)
68              return null;
69          return defaultRegistryProvider.getRegistry();
70      }
71  
72      /**
73       * Creates a registry strategy that can be used in an OSGi container. The strategy uses 
74       * OSGi contributions and contributors for the registry processing and takes advantage of 
75       * additional mechanisms available through the OSGi library.
76       * <p>
77       * The OSGi registry strategy sequentially checks the array of storage directories to 
78       * discover the location of the registry cache formed by previous invocations of the extension
79       * registry. Once found, the location is used to store registry cache. If this value 
80       * is <code>null</code> then caching of the registry content is disabled.
81       * </p><p>
82       * The cache read-only array is an array the same length as the storage directory array. 
83       * It contains boolean values indicating whether or not each storage directory is read-only. 
84       * If the value at an index is <code>true</code> then the location at the corresponding index 
85       * in the storage directories array is read-only; if <code>false</code> then the cache location 
86       * is read-write. The array can be <code>null</code> if the <code>storageDirs</code> parameter 
87       * is <code>null</code>.
88       * </p><p>
89       * The master token should be passed to the OSGi registry strategy to permit it to perform 
90       * contributions to the registry.
91       * </p><p>
92       * <b>Note:</b> This class/interface is part of an interim API that is still under 
93       * development and expected to change significantly before reaching stability. 
94       * It is being made available at this early stage to solicit feedback from pioneering 
95       * adopters on the understanding that any code that uses this API will almost certainly 
96       * be broken (repeatedly) as the API evolves.
97       * </p>
98       * @param storageDirs array of file system directories or <code>null</code>
99       * @param cacheReadOnly array of read only attributes or <code>null</code>
100      * @param token control token for the registry
101      * @return registry strategy that can be used in an OSGi container
102      * @see #createRegistry(RegistryStrategy, Object, Object)
103      */
104     public static RegistryStrategy createOSGiStrategy(File  [] storageDirs, boolean[] cacheReadOnly, Object   token) {
105         return new RegistryStrategyOSGI(storageDirs, cacheReadOnly, token);
106     }
107 
108     /**
109      * Use this method to specify the default registry provider. The default registry provider
110      * is immutable in the sense that it can be set only once during the application runtime.
111      * Attempts to change the default registry provider will cause an exception to be thrown.
112      * <p>
113      * The given registry provider must not be <code>null</code>.
114      * </p><p>
115      * <b>Note:</b> This class/interface is part of an interim API that is still under 
116      * development and expected to change significantly before reaching stability. 
117      * It is being made available at this early stage to solicit feedback from pioneering 
118      * adopters on the understanding that any code that uses this API will almost certainly 
119      * be broken (repeatedly) as the API evolves.
120      * </p>
121      * @see RegistryFactory#getRegistry()
122      * @param provider extension registry provider
123      * @throws CoreException if a default registry provider was already set for this application
124      */
125     public static void setDefaultRegistryProvider(IRegistryProvider provider) throws CoreException {
126         RegistryProviderFactory.setDefault(provider);
127     }
128 }
129
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags