RegistryInfrastructure


1   // Copyright 2004, 2005 The Apache Software Foundation
2   //
3   // Licensed under the Apache License, Version 2.0 (the "License");
4   // you may not use this file except in compliance with the License.
5   // You may obtain a copy of the License at
6   //
7   //     http://www.apache.org/licenses/LICENSE-2.0
8   //
9   // Unless required by applicable law or agreed to in writing, software
10  // distributed under the License is distributed on an "AS IS" BASIS,
11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  // See the License for the specific language governing permissions and
13  // limitations under the License.
14  
15  package org.apache.hivemind.internal;
16  
17  import java.util.List  ;
18  import java.util.Locale  ;
19  
20  import org.apache.hivemind.ErrorHandler;
21  
22  /**
23   * Extension of {@link org.apache.hivemind.Registry} provided by some internals of HiveMind to
24   * faciliate the creation of services and configurations.
25   * 
26   * @author Howard Lewis Ship
27   */
28  public interface RegistryInfrastructure
29  {
30      /**
31       * Obtains a service from the registry. Typically, what's returned is a proxy, but that's
32       * irrelevant to the caller, which simply will invoke methods of the service interface.
33       * 
34       * @param serviceId
35       *            the fully qualified id of the service to obtain
36       * @param serviceInterface
37       *            the class to which the service will be cast
38       * @param module
39       *            the referencing module, used for visibility checks (null means no module, which
40       *            requires that the service be public)
41       * @return the service
42       * @throws org.apache.hivemind.ApplicationRuntimeException
43       *             if the service does not exist (or is not visible), or if it can't be cast to the
44       *             specified service interface
45       */
46  
47      public Object   getService(String   serviceId, Class   serviceInterface, Module module);
48  
49      /**
50       * Finds a service that implements the provided interface. Exactly one such service may exist or
51       * an exception is thrown.
52       * 
53       * @param serviceInterface
54       *            used to locate the service
55       * @param module
56       *            the referencing module, used for visibility checks. If null, then only public
57       *            service points will be considered.
58       * @throws org.apache.hivemind.ApplicationRuntimeException
59       *             if either 0, or more than 1, service point is visible to the module
60       */
61      public Object   getService(Class   serviceInterface, Module module);
62  
63       /**
64       * Returns the specified configuration.
65       * 
66       * @param configurationId
67       *            the fully qualified id of the configuration
68       * @param module
69       *            the referencing module, used for visibility checks (null means no module, which
70       *            requires that the configuration be public)
71       * @return  the configuration
72       * @throws org.apache.hivemind.ApplicationRuntimeException
73       *             if no such configuration extension point exists (or visible)
74       */
75      public Object   getConfiguration(String   configurationId, Module module);
76      
77      /**
78       * Finds a configuration of the specified type. Exactly one such configuration may exist or
79       * an exception is thrown.
80       * 
81       * @param configurationType
82       *            the configuration type
83       * @param module
84       *            the referencing module, used for visibility checks (null means no module, which
85       *            requires that the configuration be public)
86       * @return  the configuration
87       * @throws org.apache.hivemind.ApplicationRuntimeException
88       *             if no such configuration extension point exists (or visible)
89       */
90      public Object   getConfiguration(Class   configurationType, Module module);
91      
92      /**
93       * Returns the configuration point.
94       * 
95       * @param configurationId
96       *            the fully qualified id of the configuration
97       * @param module
98       *            the referencing module, used for visibility checks (null means no module, which
99       *            requires that the configuration be public)
100      * @return ConfigurationPoint matching the configuration id
101      * @throws org.apache.hivemind.ApplicationRuntimeException
102      *             if the configurationId does not exist (or is not visible)
103      */
104 
105     public ConfigurationPoint getConfigurationPoint(String   configurationId, Module module);
106 
107     /**
108      * Returns the identified service extension point.
109      * 
110      * @param serviceId
111      *            fully qualified id of the service point
112      * @param module
113      *            the referencing module, used for visibility checks (null means no module, which
114      *            requires that the service be public)
115      * @throws org.apache.hivemind.ApplicationRuntimeException
116      *             if no such service extension point exists (or is visible to the module)
117      */
118 
119     public ServicePoint getServicePoint(String   serviceId, Module module);
120 
121     /**
122      * Returns a named service-model factory
123      */
124 
125     public ServiceModelFactory getServiceModelFactory(String   name);
126 
127     /**
128      * Returns the locale for which the registry was created.
129      */
130 
131     public Locale   getLocale();
132 
133     /**
134      * Returns the {@link org.apache.hivemind.ErrorHandler} for this Registry.
135      */
136 
137     public ErrorHandler getErrorHander();
138 
139     /**
140      * Returns true if a configuration for the specified id exists (and is visible to the specified
141      * module).
142      * 
143      * @param configurationId
144      *            to search for
145      * @param module
146      *            the configuration must be visible to, or null for no module (the application's
147      *            view
148      * @return true if a configuration for the specified id exists (and is visible to the module)
149      * @since 1.1
150      */
151     public boolean containsConfiguration(String   configurationId, Module module);
152 
153     /**
154      * Returns true if a single service exists which implements the specified service interface and
155      * is visible to the given module.
156      * 
157      * @param serviceInterface
158      * @param module
159      *            the service must be visible to the module (or null for the application's view)
160      * @return true if a single visible service for the specified service interface exists
161      * @since 1.1
162      */
163     public boolean containsService(Class   serviceInterface, Module module);
164 
165     /**
166      * Returns true if a single service with the given id exists which implements the specified
167      * service interface and is visible to the given module.
168      * 
169      * @param serviceId
170      * @param serviceInterface
171      * @param module
172      *            the service must be visible to the module (or null for the application's view)
173      * @return true if a single visible service for the specified service id and service interface
174      *         exists
175      * @since 1.1
176      */
177     public boolean containsService(String   serviceId, Class   serviceInterface, Module module);
178 
179     /**
180      * Invoked once, just after the registry infrastructure is constructed. One time startup
181      * operations occur, including execution of any contributions to <code>hivemind.Startup</code>.
182      * 
183      * @since 1.1
184      */
185 
186     public void startup();
187 
188     /**
189      * Shuts down the registry; this notifies all
190      * {@link org.apache.hivemind.events.RegistryShutdownListener} services and objects. Once the
191      * registry is shutdown, it is no longer valid to obtain new services or configurations, or even
192      * use existing services and configurations.
193      * 
194      * @since 1.1
195      */
196 
197     public void shutdown();
198 
199     /**
200      * To be invoked at the start of each request in a multi-threaded environment. Ensures that the
201      * receiving Registry will be used if any service proxies are de-serialized.
202      * 
203      * @since 1.1
204      * @see org.apache.hivemind.internal.ser.ServiceSerializationHelper
205      * @see org.apache.hivemind.internal.ser.ServiceSerializationSupport
206      */
207 
208     public void setupThread();
209 
210     /**
211      * Convienience for invoking
212      * {@link org.apache.hivemind.service.ThreadEventNotifier#fireThreadCleanup()}.
213      * 
214      * @since 1.1
215      */
216 
217     public void cleanupThread();
218 
219     /**
220      * @param serviceInterface
221      */
222     public List   getServiceIds(Class   serviceInterface);
223 
224     /**
225      * Returns the module with the corresponding module id.
226      * 
227      * @param moduleId
228      * @return the module with the corresponding module id
229      */
230     public Module getModule(String   moduleId);
231     
232 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags