1   /*
2    * Copyright 2003 - 2013 The eFaps Team
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *     http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   *
16   * Revision:        $Rev$
17   * Last Changed:    $Date$
18   * Last Changed By: $Author$
19   */
20  
21  package org.efaps.db.store;
22  
23  import java.io.InputStream;
24  import java.io.OutputStream;
25  
26  import javax.transaction.xa.XAResource;
27  
28  import org.efaps.db.Instance;
29  import org.efaps.util.EFapsException;
30  
31  /**
32   * Interface for the StoreResource used to archive files in eFaps.
33   *
34   * @author The eFaps Team
35   * @version $Id$
36   */
37  public interface Resource
38      extends XAResource
39  {
40      /**
41       * Store resource could implement the possibility to compress and uncompress
42       * data while writing to and reading from files.
43       */
44      enum Compress
45      {
46          /** File should not be compressed.*/
47          NONE,
48          /** File should be compressed using zip.*/
49          ZIP,
50          /** File should  be compressed using gzip.*/
51          GZIP
52      };
53  
54      /**
55       * The store resource could handle three different
56       * events:
57       * <ul>
58       * <li>delete</li>
59       * <li>write</li>
60       * <li>read</li>
61       * </ul>
62       * These three events are defined here and set in instance variable
63       * {@link #storeEvent}.
64       */
65      enum StoreEvent
66      {
67          /** delete. */
68          DELETE,
69          /** write. */
70          WRITE,
71          /** read. */
72          READ,
73          /** not known yet.    **/
74          UNKNOWN;
75      };
76  
77      /**
78       * Method to open the Resource.
79       *
80       * @param _event Event the store is opened for
81       * @throws EFapsException on error
82       */
83      void open(StoreEvent _event) throws EFapsException;
84  
85      /**
86       * The input stream with the attached content of the object returned.
87       *
88       * @return input stream with the content of the file
89       * @throws EFapsException if an error occurs
90       */
91      InputStream read() throws EFapsException;
92  
93      /**
94       * Writes the file with the given input stream.
95       *
96       * @param _in       input stream
97       * @param _size     size of the data to write (or negative if the size is
98       *                  not known)
99       * @param _fileName name of the file
100      * @return length of the file which is stored
101      * @throws EFapsException if an error occurs
102      */
103     long write(final InputStream _in,
104                final long _size,
105                final String _fileName)
106         throws EFapsException;
107 
108     /**
109      * Will delete the file.
110      *
111      * @throws EFapsException if an error occurs
112      */
113     void delete() throws EFapsException;
114 
115     /**
116      * Method to commit the Resource.
117      *
118      * @throws EFapsException on error
119      */
120     void commit() throws EFapsException;
121 
122     /**
123      * @return if the Resource was opened.
124      */
125     boolean isOpened();
126 
127     /**
128      * Method to open the Resource.
129      *
130      * @throws EFapsException on error
131      */
132     void abort() throws EFapsException;
133 
134     /**
135      * The output stream is written with the content of the file. From method
136      * {@link #read()} the input stream is used and copied into the output
137      * stream.
138      *
139      * @param _out    output stream where the file content must be written
140      * @throws EFapsException if an error occurs
141      */
142     void read(final OutputStream _out) throws EFapsException;
143 
144 
145     /**
146      * Get the name of the file.
147      * @return filename
148      * @throws EFapsException on error
149      */
150     String getFileName() throws EFapsException;
151 
152     /**
153      * Get the Length of the file in byte.
154      * @return filelength
155      * @throws EFapsException on error
156      */
157     Long getFileLength() throws EFapsException;
158 
159     /**
160      * Method called to initialize this StoreResource.
161      * @see org.efaps.db.store.Resource#initialize(org.efaps.db.Instance,
162      *  java.util.Map, org.efaps.db.store.Resource.Compress)
163      * @param _instance     Instance of the object this StoreResource is wanted
164      *                      for
165      * @param _store        Store this StoreResource belongs to
166      * @throws EFapsException on error
167      */
168     void initialize(final Instance _instance,
169                     final Store _store)
170         throws EFapsException;
171 }