PersistentService


1   /*
2   
3      Derby - Class org.apache.derby.iapi.services.monitor.PersistentService
4   
5      Licensed to the Apache Software Foundation (ASF) under one or more
6      contributor license agreements.  See the NOTICE file distributed with
7      this work for additional information regarding copyright ownership.
8      The ASF licenses this file to you under the Apache License, Version 2.0
9      (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 org.apache.derby.io.StorageFactory;
25  
26  import org.apache.derby.iapi.error.StandardException;
27  import org.apache.derby.iapi.reference.Property;
28  
29  import java.util.Properties  ;
30  import java.util.Enumeration  ;
31  
32  import java.io.IOException  ;
33  
34  /**
35      A PersistentService modularises the access to persistent services,
36      abstracting out details such as finding the list of services to
37      be started at boot time, finding the service.properties file
38      and creating and deleting the persistent storage for a service.
39  <P>
40      These modules must only be used by the monitor.
41  <P>
42      Possible examples of implementations are:
43  
44      <UL>
45      <LI> Store services in a directory in the file system.
46      <LI> Store services in a zip file
47      <LI> Service data is provided by a web server
48      <LI> Service data is stored on the class path.
49      </UL>
50  <P>
51      This class also serves as the registry the defined name for all
52      the implementations of PersistentService. These need to be kept track
53      of as they can be used in JDBC URLS.
54  <P>
55      An implementation of PersistentService can implement ModuleSupportable
56      but must not implement ModuleControl. This is because the monitor will
57      not execute ModuleControl methods for a PersistentService.
58  */
59  
60  public interface PersistentService {
61  
62      /**
63          Service stored in a directory.
64      */
65      public static final String   DIRECTORY = "directory";
66  
67      /**
68          Service stored on the class path (can be in a zip/jar on the class path).
69      */
70      public static final String   CLASSPATH = "classpath";
71  
72      /**
73          Service stored in a jar/zip archive.
74      */
75      public static final String   JAR = "jar";
76  
77      /**
78          Service stored in a web server .
79      */
80      public static final String   HTTP = "http";
81      public static final String   HTTPS = "https";
82  
83  
84      /**
85          The typical name for the service's properties file.
86      */
87      public static final String   PROPERTIES_NAME = "service.properties";
88  
89      /**
90          The root of any stored data.
91      */
92      public static final String   ROOT = Property.PROPERTY_RUNTIME_PREFIX + "serviceDirectory";
93  
94      /**
95          The type of PersistentService used to boot the service.
96      */
97      public static final String   TYPE = Property.PROPERTY_RUNTIME_PREFIX + "serviceType";
98  
99      /**
100         Return the type of this service.
101     */
102     public String   getType();
103 
104     /**
105         Return an Enumeration of service names descriptors (Strings) that should be
106         be started at boot time by the monitor. The monitor will boot the service if getServiceProperties()
107         returns a Properties object and the properties does not indicate the service should not be
108         auto-booted.
109         <P>
110         This method may return null if there are no services that need to be booted automatically at boot time.
111 
112         <P>
113         The service name returned by the Enumeration must be in its canonical form.
114     */
115     public Enumeration   getBootTimeServices();
116 
117     /**
118         For a service return its service properties, typically from the service.properties
119         file.
120 
121         @return A Properties object or null if serviceName does not represent a valid service.
122 
123         @exception StandardException Service appears valid but the properties cannot be created.
124     */
125     public Properties   getServiceProperties(String   serviceName, Properties   defaultProperties)
126         throws StandardException;
127 
128     /**
129         @exception StandardException Properties cannot be saved.
130     */
131     public void saveServiceProperties(String   serviceName,
132                                       StorageFactory storageFactory,
133                                       Properties   properties,
134                                       boolean replace)
135         throws StandardException;
136 
137     /**
138        Save to a backup file.
139        
140         @exception StandardException Properties cannot be saved.
141     */
142     public void saveServiceProperties(String   serviceName,
143                                       Properties   properties,
144                                       boolean replace)
145         throws StandardException;
146 
147     /**
148         Returns the canonical name of the service.
149 
150         @exception StandardException Service root cannot be created.
151     */
152     public String   createServiceRoot(String   name, boolean deleteExisting)
153         throws StandardException;
154 
155     /**
156         Remove a service's root and its contents.
157     */
158     public boolean removeServiceRoot(String   serviceName);
159 
160     /**
161         Convert a service name into its canonical form. Returns null if the name
162         cannot be converted into a canonical form.
163         
164         @exception No canonical name, name probably invalid
165     */
166     public String   getCanonicalServiceName(String   name)
167         throws StandardException;
168 
169     /**
170         Return the user form of a service name. This name is only valid within
171         this system. The separator character used must be '/'
172     */
173     public String   getUserServiceName(String   serviceName);
174 
175 
176     public boolean isSameService(String   serviceName1, String   serviceName2);
177 
178     /**
179      * @return true if the PersistentService has a StorageFactory, false if not.
180      */
181     public boolean hasStorageFactory();
182     
183     /**
184      * Get an initialized StorageFactoryInstance
185      *
186      * @param useHome If true and the database name is not absolute then the database directory will be
187      *                relative to the home directory, if one is defined in the properties file.
188      * @param databaseName The name of the database (directory). The name does not include the subSubProtocol.
189      *                     If null then the storage factory will only be used to deal with the directory containing
190      *                     the databases.
191      * @param tempDirName The name of the temporary file directory set in properties. If null then a default
192      *                    directory should be used. Each database should get a separate temporary file
193      *                    directory within this one to avoid collisions.
194      * @param uniqueName A unique name that can be used to create the temporary file directory for this database.
195      *                   If null then temporary files will not be created in this StorageFactory instance.
196      *
197      * @return An initialized StorageFactory.
198      */
199     public StorageFactory getStorageFactoryInstance(boolean useHome,
200                                                     String   databaseName,
201                                                     String   tempDirName,
202                                                     String   uniqueName)
203         throws StandardException, IOException  ;
204 }
205
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags