001: /*
002:
003: Derby - Class org.apache.derby.iapi.store.access.FileResource
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.store.access;
023:
024: import org.apache.derby.iapi.error.StandardException;
025: import org.apache.derby.iapi.store.access.DatabaseInstant;
026: import org.apache.derby.io.StorageFile;
027:
028: import java.io.FileNotFoundException;
029: import java.io.IOException;
030: import java.io.InputStream;
031:
032: /**
033: Management of file resources within a database. Suitable for jar
034: files, images etc.
035:
036: <P>A file resource is identified by the pair (name,generationId).
037: Name is an arbitrary String supplied by the caller. GenerationId
038: is a non-repeating sequence number constructed by the database.
039: Within a database a (name,generationId) pair uniquely identifies
040: a version of a file resource for all time. Newer generation
041: numbers reflect newer versions of the file.
042:
043: <P>A database supports the concept of a designated current version
044: of a fileResource. The management of the current version is
045: transactional. The following rules apply
046: <OL>
047: <LI>Adding a FileResource makes the added version the current
048: version
049: <LI>Removing a FileResource removes the current version of the
050: resource. After this operation the database holds no current
051: version of the FileResoure.
052: <LI>Replacing a FileResource removes the current version of the
053: resource.
054: </OL>
055:
056: <P>For the benefit of replication, a database optionally retains
057: historic versions of stored files. These old versions are
058: useful when processing old transactions in the stage.
059: */
060: public interface FileResource {
061:
062: /**
063: The name of the jar directory
064: */
065: public static final String JAR_DIRECTORY_NAME = "jar";
066:
067: /**
068: Add a file resource, copying from the input stream.
069:
070: The InputStream will be closed by this method.
071: @param name the name of the file resource.
072: @param source an input stream for reading the content of
073: the file resource.
074: @return the generationId for the file resource. This
075: quantity increases when you replace the file resource.
076:
077: @exception StandardException some error occured.
078: */
079: public long add(String name, InputStream source)
080: throws StandardException;
081:
082: /**
083: Remove the current generation of a file resource from
084: the database.
085:
086: @param name the name of the fileResource to remove.
087: @param purgeOnCommit true means purge the fileResource
088: when the current transaction commits. false means retain
089: the file resource for use by replication.
090:
091: @exception StandardException some error occured.
092: */
093: public void remove(String name, long currentGenerationId,
094: boolean purgeOnCommit) throws StandardException;
095:
096: /**
097: Replace a file resource with a new version.
098:
099: <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 name, long currentGenerationId,
112: InputStream source, boolean purgeOnCommit)
113: throws StandardException;
114:
115: /**
116: Get the File handle to a file resource. In some situations
117: higher level code can make optimisations if it can access
118: a file as a File, rather than an output stream. If this call
119: returns null then the resouce is not accessable as a file
120: (e.g. the database is in a zip file).
121:
122: @param name The name of the fileResource
123: @param generationId the generationId of the fileResource
124:
125: @return A File object representing the file, or null if
126: the resource is not accessable as a file.
127: */
128: public StorageFile getAsFile(String name, long generationId);
129:
130: /**
131: Get the file resource as a stream.
132:
133: @exception IOException some io error occured
134: @exception FileNotFoundException file does not exist.
135: */
136: public InputStream getAsStream(String name, long generationId)
137: throws IOException;
138:
139: /**
140: * @return the separator character to be used in file names.
141: */
142: public char getSeparatorChar();
143: }
|