KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > derby > iapi > store > access > FileResource


1 /*
2
3    Derby - Class org.apache.derby.iapi.store.access.FileResource
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.store.access;
23
24 import org.apache.derby.iapi.error.StandardException;
25 import org.apache.derby.iapi.store.access.DatabaseInstant;
26 import org.apache.derby.io.StorageFile;
27
28 import java.io.FileNotFoundException JavaDoc;
29 import java.io.IOException JavaDoc;
30 import java.io.InputStream JavaDoc;
31
32 /**
33     Management of file resources within a database. Suitable for jar
34     files, images etc.
35
36     <P>A file resource is identified by the pair (name,generationId).
37     Name is an arbitrary String supplied by the caller. GenerationId
38     is a non-repeating sequence number constructed by the database.
39     Within a database a (name,generationId) pair uniquely identifies
40     a version of a file resource for all time. Newer generation
41     numbers reflect newer versions of the file.
42
43     <P>A database supports the concept of a designated current version
44     of a fileResource. The management of the current version is
45     transactional. The following rules apply
46     <OL>
47     <LI>Adding a FileResource makes the added version the current
48     version
49     <LI>Removing a FileResource removes the current version of the
50     resource. After this operation the database holds no current
51     version of the FileResoure.
52     <LI>Replacing a FileResource removes the current version of the
53     resource.
54     </OL>
55     
56     <P>For the benefit of replication, a database optionally retains
57     historic versions of stored files. These old versions are
58     useful when processing old transactions in the stage.
59 */
60 public interface FileResource {
61
62     /**
63        The name of the jar directory
64     */
65     public static final String JavaDoc JAR_DIRECTORY_NAME = "jar";
66
67     /**
68       Add a file resource, copying from the input stream.
69       
70       The InputStream will be closed by this method.
71       @param name the name of the file resource.
72       @param source an input stream for reading the content of
73              the file resource.
74       @return the generationId for the file resource. This
75       quantity increases when you replace the file resource.
76
77       @exception StandardException some error occured.
78     */
79     public long add(String JavaDoc name,InputStream JavaDoc source)
80         throws StandardException;
81
82     /**
83       Remove the current generation of a file resource from
84       the database.
85
86       @param name the name of the fileResource to remove.
87       @param purgeOnCommit true means purge the fileResource
88              when the current transaction commits. false means retain
89              the file resource for use by replication.
90       
91       @exception StandardException some error occured.
92       */
93     public void remove(String JavaDoc name, long currentGenerationId, boolean purgeOnCommit)
94         throws StandardException;
95
96     /**
97       Replace a file resource with a new version.
98
99       <P>The InputStream will be closed by this method.
100
101       @param name the name of the file resource.
102       @param source an input stream for reading the content of
103       the file resource.
104       @param purgeOnCommit true means purge the existing version of
105              fileResource when the current transaction commits. false
106              means retain the existing version for use by replication.
107       @return the generationId for the new 'current' version of the
108               file resource.
109       @exception StandardException some error occured.
110     */
111     public long replace(String JavaDoc name, long currentGenerationId, InputStream JavaDoc source,boolean purgeOnCommit)
112         throws StandardException;
113
114     /**
115       Get the File handle to a file resource. In some situations
116       higher level code can make optimisations if it can access
117       a file as a File, rather than an output stream. If this call
118       returns null then the resouce is not accessable as a file
119       (e.g. the database is in a zip file).
120       
121       @param name The name of the fileResource
122       @param generationId the generationId of the fileResource
123       
124       @return A File object representing the file, or null if
125       the resource is not accessable as a file.
126       */
127     public StorageFile getAsFile(String JavaDoc name, long generationId);
128
129     /**
130       Get the file resource as a stream.
131
132       @exception IOException some io error occured
133       @exception FileNotFoundException file does not exist.
134     */
135     public InputStream JavaDoc getAsStream(String JavaDoc name, long generationId)
136         throws IOException JavaDoc;
137
138     /**
139      * @return the separator character to be used in file names.
140      */
141     public char getSeparatorChar();
142 }
143
Popular Tags