001: /*
002:
003: Derby - Class org.apache.derby.iapi.services.monitor.ModuleFactory
004:
005: Licensed to the Apache Software Foundation (ASF) under one or more
006: contributor license agreements. See the NOTICE file distributed with
007: this work for additional information regarding copyright ownership.
008: The ASF licenses this file to you under the Apache License, Version 2.0
009: (the "License"); you may not use this file except in compliance with
010: the License. You may obtain a copy of the License at
011:
012: http://www.apache.org/licenses/LICENSE-2.0
013:
014: Unless required by applicable law or agreed to in writing, software
015: distributed under the License is distributed on an "AS IS" BASIS,
016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: See the License for the specific language governing permissions and
018: limitations under the License.
019:
020: */
021:
022: package org.apache.derby.iapi.services.monitor;
023:
024: import org.apache.derby.iapi.services.info.ProductVersionHolder;
025: import org.apache.derby.iapi.error.StandardException;
026: import org.apache.derby.iapi.services.stream.InfoStreams;
027: import org.apache.derby.iapi.services.monitor.PersistentService;
028: import org.apache.derby.iapi.services.loader.InstanceGetter;
029:
030: import java.util.Properties;
031: import java.util.Locale;
032: import java.io.InputStream;
033: import java.io.IOException;
034:
035: /**
036: The monitor provides a central registry for all modules in the system,
037: and manages loading, starting, and finding them.
038: */
039:
040: public interface ModuleFactory {
041:
042: /**
043: * Find the module in the system with the given module protocol,
044: * protocolVersion and identifier.
045:
046: * @return The module instance if found, or null.
047: */
048: public Object findModule(Object service, String protocol,
049: String identifier);
050:
051: /**
052: Return the name of the service that the passed in module lives in.
053: */
054: public String getServiceName(Object serviceModule);
055:
056: /**
057: Return the locale of the service that the passed in module lives in.
058: Will return null if no-locale has been defined.
059: */
060: public Locale getLocale(Object serviceModule);
061:
062: /**
063: Translate a string of the form ll[_CC[_variant]] to a Locale.
064: This is in the Monitor because we want this translation to be
065: in only one place in the code.
066: */
067: public Locale getLocaleFromString(String localeDescription)
068: throws StandardException;
069:
070: /**
071: Set the locale for the service *outside* of boot time.
072:
073: @param userDefinedLocale A String in the form xx_YY, where xx is the
074: language code and YY is the country code.
075:
076: @return The new Locale for the service
077:
078: @exception StandardException Thrown on error
079: */
080: public Locale setLocale(Object serviceModule,
081: String userDefinedLocale) throws StandardException;
082:
083: /**
084: Set the locale for the service at boot time. The passed-in
085: properties must be the one passed to the boot method.
086:
087: @exception StandardException Cloudscape error.
088: */
089: public Locale setLocale(Properties serviceProperties,
090: String userDefinedLocale) throws StandardException;
091:
092: /**
093: Return the PersistentService object for a service.
094: Will return null if the service does not exist.
095: */
096: public PersistentService getServiceType(Object serviceModule);
097:
098: /**
099: * Return the PersistentService for a subsubprotocol.
100: *
101: * @return the PersistentService or null if it does not exist
102: *
103: * @exception StandardException
104: */
105: public PersistentService getServiceProvider(String subSubProtocol)
106: throws StandardException;
107:
108: public Properties getApplicationProperties();
109:
110: /**
111: Shut down the complete system that was started by this Monitor. Will
112: cause the stop() method to be called on each loaded module.
113: */
114: public void shutdown();
115:
116: /**
117: Shut down a service that was started by this Monitor. Will
118: cause the stop() method to be called on each loaded module.
119: Requires that a context stack exist.
120: */
121: public void shutdown(Object service);
122:
123: /**
124: Obtain a class that supports the given identifier.
125:
126: @param identifier identifer to associate with class
127:
128: @return a reference InstanceGetter
129:
130: @exception StandardException See Monitor.classFromIdentifier
131: */
132: public InstanceGetter classFromIdentifier(int identifier)
133: throws StandardException;
134:
135: /**
136: Obtain an new instance of a class that supports the given identifier.
137:
138: @param identifier identifer to associate with class
139:
140: @return a reference to a newly created object
141:
142: @exception StandardException See Monitor.newInstanceFromIdentifier
143:
144: */
145: public Object newInstanceFromIdentifier(int identifier)
146: throws StandardException;
147:
148: /**
149: Return the environment object that this system was booted in.
150: This is a free form object that is set by the method the
151: system is booted. For example when running in a Marimba system
152: it is set to the maribma application context. In most environments
153: it will be set to a java.io.File object representing the system home directory.
154: Code that call this method usualy have predefined knowledge of the type of the returned object, e.g.
155: Marimba store code knows that this will be set to a marimba application
156: context.
157: */
158: public Object getEnvironment();
159:
160: /**
161: Return an array of the service identifiers that are running and
162: implement the passed in protocol (java interface class name).
163: This list is a snapshot of the current running systesm, once
164: the call returns the service may have been shutdown or
165: new ones added.
166:
167: @return The list of service names, if no services exist that
168: implement the protocol an array with zero elements is returned.
169: */
170: public String[] getServiceList(String protocol);
171:
172: /**
173: Start a persistent service.
174: <BR>
175: <B>Do not call directly - use Monitor.startPersistentService()</B>
176:
177: <P> The poperty set passed in is for boot options for the modules
178: required to start the service. It does not support defining different
179: or new modules implementations.
180:
181: @param serviceName Name of the service to be started
182: @param properties Property set made available to all modules booted
183: for this service, through their ModuleControl.boot method.
184:
185: @return true if the service type is handled by the monitor, false if it isn't
186:
187: @exception StandardException An attempt to start the service failed.
188:
189: @see Monitor#startPersistentService
190: */
191: public boolean startPersistentService(String serviceName,
192: Properties properties) throws StandardException;
193:
194: /**
195: Create a persistent service.
196: <BR>
197: <B>Do not call directly - use Monitor.startPersistentService()</B>
198:
199: @exception StandardException An attempt to create the service failed.
200:
201: @see Monitor#createPersistentService
202: */
203: public Object createPersistentService(String factoryInterface,
204: String serviceName, Properties properties)
205: throws StandardException;
206:
207: public void removePersistentService(String name)
208: throws StandardException;
209:
210: /**
211: Start a non-persistent service.
212:
213: <BR>
214: <B>Do not call directly - use Monitor.startNonPersistentService()</B>
215:
216: @exception StandardException An attempt to start the service failed.
217:
218: @see Monitor#startNonPersistentService
219: */
220: public Object startNonPersistentService(String factoryInterface,
221: String serviceName, Properties properties)
222: throws StandardException;
223:
224: /**
225: Find a service.
226:
227: <BR>
228: <B>Do not call directly - use Monitor.findService()</B>
229:
230: @return a refrence to a module represeting the service or null if the service does not exist.
231:
232: @see Monitor#findService
233: */
234: public Object findService(String protocol, String identifier);
235:
236: /**
237: Start a module.
238:
239: <BR>
240: <B>Do not call directly - use Monitor.startSystemModule() or Monitor.bootServiceModule()</B>
241:
242: @exception StandardException An attempt to start the module failed.
243:
244: @see Monitor#startSystemModule
245: @see Monitor#bootServiceModule
246: */
247: public Object startModule(boolean create, Object service,
248: String protocol, String identifier, Properties properties)
249: throws StandardException;
250:
251: /**
252: Get the defined default system streams object.
253: */
254: public InfoStreams getSystemStreams();
255:
256: /**
257: Start all services identified by derby.service.*
258: in the property set. If bootAll is true the services
259: that are persistent will be booted.
260: */
261: public void startServices(Properties properties, boolean bootAll);
262:
263: /**
264: Return a property from the JVM's system set.
265: In a Java2 environment this will be executed as a privileged block
266: if and only if the property starts with 'derby.'.
267: If a SecurityException occurs, null is returned.
268: */
269: public String getJVMProperty(String key);
270:
271: /**
272: Get a newly created background thread.
273: The thread is set to be a daemon but is not started.
274: */
275: public Thread getDaemonThread(Runnable task, String name,
276: boolean setMinPriority);
277:
278: /**
279: Set the priority of the current thread.
280: If the current thread was not returned by getDaemonThread() then no action is taken.
281: */
282: public void setThreadPriority(int priority);
283:
284: public ProductVersionHolder getEngineVersion();
285:
286: /**
287: * Get the UUID factory for the system. The UUID factory provides
288: * methods to create and recreate database unique identifiers.
289: */
290: public org.apache.derby.iapi.services.uuid.UUIDFactory getUUIDFactory();
291:
292: /**
293: * Get the Timer factory for the system. The Timer factory provides
294: * access to Timer objects for various purposes.
295: *
296: * @return the system's Timer factory.
297: */
298: public org.apache.derby.iapi.services.timer.TimerFactory getTimerFactory();
299: }
|