01: /*
02:
03: Derby - Class org.apache.derby.iapi.services.monitor.ModuleControl
04:
05: Licensed to the Apache Software Foundation (ASF) under one or more
06: contributor license agreements. See the NOTICE file distributed with
07: this work for additional information regarding copyright ownership.
08: The ASF licenses this file to you under the Apache License, Version 2.0
09: (the "License"); you may not use this file except in compliance with
10: the License. You may obtain a copy of the License at
11:
12: http://www.apache.org/licenses/LICENSE-2.0
13:
14: Unless required by applicable law or agreed to in writing, software
15: distributed under the License is distributed on an "AS IS" BASIS,
16: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17: See the License for the specific language governing permissions and
18: limitations under the License.
19:
20: */
21:
22: package org.apache.derby.iapi.services.monitor;
23:
24: import java.util.Properties;
25: import org.apache.derby.iapi.error.StandardException;
26:
27: /**
28: ModuleControl is <B>optionally</B> implemented by a module's factory class.
29: */
30:
31: public interface ModuleControl {
32:
33: /**
34: Boot this module with the given properties. Creates a module instance
35: that can be found using the findModule() methods of Monitor.
36: The module can only be found using one of these findModule() methods
37: once this method has returned.
38: <P>
39: An implementation's boot method can throw StandardException. If it
40: is thrown the module is not registered by the monitor and therefore cannot
41: be found through a findModule(). In this case the module's stop() method
42: is not called, thus throwing this exception must free up any
43: resources.
44: <P>
45: When create is true the contents of the properties object
46: will be written to the service.properties of the persistent
47: service. Thus any code that requires an entry in service.properties
48: must <B>explicitly</B> place the value in this properties set
49: using the put method.
50: <BR>
51: Typically the properties object contains one or more default
52: properties sets, which are not written out to service.properties.
53: These default sets are how callers modify the create process. In a
54: JDBC connection database create the first set of defaults is a properties
55: object that contains the attributes that were set on the jdbc:derby: URL.
56: This attributes properties set has the second default properties set as
57: its default. This set (which could be null) contains the properties
58: that the user set on their DriverManager.getConnection() call, and are thus
59: not owned by cloudscape code, and thus must not be modified by cloudscape
60: code.
61: <P>
62: When create is false the properties object contains all the properties
63: set in the service.properties file plus a <B>limited</B> number of
64: attributes from the JDBC URL attributes or connection properties set.
65: This avoids properties set by the user compromising the boot process.
66: An example of a property passed in from the JDBC world is the bootPassword
67: for encrypted databases.
68:
69: <P>
70: Code should not hold onto the passed in properties reference after boot time
71: as its contents may change underneath it. At least after the complete boot
72: is completed, the links to all the default sets will be removed.
73:
74: @exception StandardException Module cannot be started.
75:
76: @see Monitor
77: @see ModuleFactory
78:
79: */
80:
81: public void boot(boolean create, Properties properties)
82: throws StandardException;
83:
84: /**
85: Stop the module.
86:
87: The module may be found via a findModule() method until some time after
88: this method returns. Therefore the factory must be prepared to reject requests
89: to it once it has been stopped. In addition other modules may cache a reference
90: to the module and make requests of it after it has been stopped, these requests
91: should be rejected as well.
92:
93: @see Monitor
94: @see ModuleFactory
95: */
96:
97: public void stop();
98:
99: }
|