001: /*
002:
003: Derby - Class org.apache.derby.iapi.services.monitor.PersistentService
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.io.StorageFactory;
025:
026: import org.apache.derby.iapi.error.StandardException;
027: import org.apache.derby.iapi.reference.Property;
028:
029: import java.util.Properties;
030: import java.util.Enumeration;
031:
032: import java.io.IOException;
033:
034: /**
035: A PersistentService modularises the access to persistent services,
036: abstracting out details such as finding the list of services to
037: be started at boot time, finding the service.properties file
038: and creating and deleting the persistent storage for a service.
039: <P>
040: These modules must only be used by the monitor.
041: <P>
042: Possible examples of implementations are:
043:
044: <UL>
045: <LI> Store services in a directory in the file system.
046: <LI> Store services in a zip file
047: <LI> Service data is provided by a web server
048: <LI> Service data is stored on the class path.
049: </UL>
050: <P>
051: This class also serves as the registry the defined name for all
052: the implementations of PersistentService. These need to be kept track
053: of as they can be used in JDBC URLS.
054: <P>
055: An implementation of PersistentService can implement ModuleSupportable
056: but must not implement ModuleControl. This is because the monitor will
057: not execute ModuleControl methods for a PersistentService.
058: */
059:
060: public interface PersistentService {
061:
062: /**
063: Service stored in a directory.
064: */
065: public static final String DIRECTORY = "directory";
066:
067: /**
068: Service stored on the class path (can be in a zip/jar on the class path).
069: */
070: public static final String CLASSPATH = "classpath";
071:
072: /**
073: Service stored in a jar/zip archive.
074: */
075: public static final String JAR = "jar";
076:
077: /**
078: Service stored in a web server .
079: */
080: public static final String HTTP = "http";
081: public static final String HTTPS = "https";
082:
083: /**
084: The typical name for the service's properties file.
085: */
086: public static final String PROPERTIES_NAME = "service.properties";
087:
088: /**
089: The root of any stored data.
090: */
091: public static final String ROOT = Property.PROPERTY_RUNTIME_PREFIX
092: + "serviceDirectory";
093:
094: /**
095: The type of PersistentService used to boot the service.
096: */
097: public static final String TYPE = Property.PROPERTY_RUNTIME_PREFIX
098: + "serviceType";
099:
100: /**
101: Return the type of this service.
102: */
103: public String getType();
104:
105: /**
106: Return an Enumeration of service names descriptors (Strings) that should be
107: be started at boot time by the monitor. The monitor will boot the service if getServiceProperties()
108: returns a Properties object and the properties does not indicate the service should not be
109: auto-booted.
110: <P>
111: This method may return null if there are no services that need to be booted automatically at boot time.
112:
113: <P>
114: The service name returned by the Enumeration must be in its canonical form.
115: */
116: public Enumeration getBootTimeServices();
117:
118: /**
119: For a service return its service properties, typically from the service.properties
120: file.
121:
122: @return A Properties object or null if serviceName does not represent a valid service.
123:
124: @exception StandardException Service appears valid but the properties cannot be created.
125: */
126: public Properties getServiceProperties(String serviceName,
127: Properties defaultProperties) throws StandardException;
128:
129: /**
130: @exception StandardException Properties cannot be saved.
131: */
132: public void saveServiceProperties(String serviceName,
133: StorageFactory storageFactory, Properties properties,
134: boolean replace) throws StandardException;
135:
136: /**
137: Save to a backup file.
138:
139: @exception StandardException Properties cannot be saved.
140: */
141: public void saveServiceProperties(String serviceName,
142: Properties properties, boolean replace)
143: throws StandardException;
144:
145: /**
146: Returns the canonical name of the service.
147:
148: @exception StandardException Service root cannot be created.
149: */
150: public String createServiceRoot(String name, boolean deleteExisting)
151: throws StandardException;
152:
153: /**
154: Remove a service's root and its contents.
155: */
156: public boolean removeServiceRoot(String serviceName);
157:
158: /**
159: Convert a service name into its canonical form. Returns null if the name
160: cannot be converted into a canonical form.
161:
162: @exception No canonical name, name probably invalid
163: */
164: public String getCanonicalServiceName(String name)
165: throws StandardException;
166:
167: /**
168: Return the user form of a service name. This name is only valid within
169: this system. The separator character used must be '/'
170: */
171: public String getUserServiceName(String serviceName);
172:
173: public boolean isSameService(String serviceName1,
174: String serviceName2);
175:
176: /**
177: * @return true if the PersistentService has a StorageFactory, false if not.
178: */
179: public boolean hasStorageFactory();
180:
181: /**
182: * Get an initialized StorageFactoryInstance
183: *
184: * @param useHome If true and the database name is not absolute then the database directory will be
185: * relative to the home directory, if one is defined in the properties file.
186: * @param databaseName The name of the database (directory). The name does not include the subSubProtocol.
187: * If null then the storage factory will only be used to deal with the directory containing
188: * the databases.
189: * @param tempDirName The name of the temporary file directory set in properties. If null then a default
190: * directory should be used. Each database should get a separate temporary file
191: * directory within this one to avoid collisions.
192: * @param uniqueName A unique name that can be used to create the temporary file directory for this database.
193: * If null then temporary files will not be created in this StorageFactory instance.
194: *
195: * @return An initialized StorageFactory.
196: */
197: public StorageFactory getStorageFactoryInstance(boolean useHome,
198: String databaseName, String tempDirName, String uniqueName)
199: throws StandardException, IOException;
200: }
|