1 /**
2 *
3 */
4 package org.jscsi.target.storage;
5
6
7 import java.io.IOException;
8
9 import org.jscsi.target.scsi.cdb.CommandDescriptorBlock;
10
11
12 /**
13 * This is an abstract super class offering methods for storage and retrieval of data, as well as emulating some
14 * properties of block storage devices.
15 * <p>
16 * All index and length parameters used by the read and write methods are referring to bytes, unlike the values sent in
17 * {@link CommandDescriptorBlock} s.
18 *
19 * @author Andreas Ergenzinger
20 */
21 public interface IStorageModule {
22
23 /**
24 * A fictitious block size.
25 */
26 public static final int VIRTUAL_BLOCK_SIZE = 512;
27
28 /**
29 * This method can be used for checking if a (series of) I/O operations will result in an {@link IOException} due to
30 * trying to access blocks outside the medium's boundaries.
31 * <p>
32 * The SCSI standard requires checking for these boundary violations right after receiving a read or write command,
33 * so that an appropriate error message can be returned to the initiator. Therefore this method must be called prior
34 * to each read or write sequence.
35 * <p>
36 * The values returned by this method and their meaning with regard to the interval [0, {@link #getSizeInBlocks()} -
37 * 1] are shown in the following table:
38 * <p>
39 * <table border="1">
40 * <tr>
41 * <th>Return Value</th>
42 * <th>Meaning</th>
43 * </tr>
44 * <tr>
45 * <td>0</td>
46 * <td>no boundaries are violated</td>
47 * </tr>
48 * <tr>
49 * <td>1</td>
50 * <td>the <i>logicalBlockAddress</i> parameter lies outside of the interval</td>
51 * </tr>
52 * <tr>
53 * <td>2</td>
54 * <td>the interval [<i>logicalBlockAddress</i>, <i>logicalBlockAddress</i> + <i>transferLengthInBlocks</i>]<br/>
55 * lies outside of the interval, or <i>transferLengthInBlocks</i> is negative</td>
56 * </tr>
57 * </table>
58 * <p>
59 * Note that the parameters of this method are referring to blocks, not to byte indices.
60 *
61 * @param logicalBlockAddress the index of the first block of data to be read or written
62 * @param transferLengthInBlocks the total number of consecutive blocks about to be read or written
63 * @return see table in description
64 */
65 int checkBounds (final long logicalBlockAddress, final int transferLengthInBlocks);
66
67 /**
68 * Returns the storage space size in bytes divided by the block size in bytes (rounded down).
69 *
70 * @return the virtual amount of storage blocks available
71 */
72 long getSizeInBlocks ();
73
74 /**
75 * Copies bytes from storage to the passed byte array.
76 *
77 * @param bytes the array into which the data will be copied will be filled with data from storage
78 * @param storageIndex the position of the first byte to be copied
79 * @throws IOException
80 */
81 void read (byte[] bytes, long storageIndex) throws IOException;
82
83 /**
84 * Saves part of the passed byte array's content.
85 *
86 * @param bytes the source of the data to be stored
87 * @param storageIndex byte offset in the storage area
88 * @throws IOException
89 */
90 void write (byte[] bytes, long storageIndex) throws IOException;
91
92 /**
93 * Closing the storage.
94 *
95 * @throws IOException to be closed
96 */
97 void close () throws IOException;
98
99 }