1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19 package net.sf.dexterim.oscar;
20
21 import net.sf.dexterim.oscar.entity.ByteBased;
22 import net.sf.dexterim.oscar.entity.DWord;
23 import net.sf.dexterim.oscar.entity.Word;
24
25 /***
26 * @author Christoph Walcher
27 */
28 public abstract class OscarByteBuffer {
29
30 /*** Sets the position to newPosition and returns the old position.
31 * May throw an ArrayIndexOutOfBounds exception if position was set beyond
32 * the end of the underlying data structure.
33 *
34 * @param position new Position
35 * @return old Position
36 */
37 public abstract int position(int position);
38
39 /*** Returns the current position.
40 * @return current Position in Buffer
41 */
42 public abstract int position();
43
44 /*** Returns the current size of the buffer. For dynamic Buffers this size
45 * may change after calling writer or position.
46 *
47 * @return current size
48 */
49 public abstract int size();
50
51 /*** Returns last position with data available
52 *
53 * @return fill
54 */
55 public abstract int fill();
56
57 /*** Strips the OscarByteBuffer by setting the fill to the current position.
58 *
59 * @return current Position
60 */
61 public abstract int strip();
62
63 /*** Returns the data chunk at current position as Word.
64 * Throws an ArrayIndexOutOfBounds Exception if not enough bytes are present
65 * in Buffer to construct a Word value.
66 *
67 * @return Word value at current position
68 */
69 public abstract Word getWord();
70
71 /*** Returns the data chunk at current position as DWord.
72 * Throws an ArrayIndexOutOfBounds Exception if not enough bytes are present
73 * in Buffer to construct a DWord value.
74 *
75 * @return DWord value at current position
76 */
77 public abstract DWord getDWord();
78
79 /*** Returns byte at current position.
80 * Throws an ArrayIndexOutOfBounds Exception if position() >= size()
81 *
82 * @return byte value at current position
83 */
84 public abstract int getByte();
85
86 /*** Writes a ByteBased value at current position. This may throw an
87 * ArrayIndexOutOfBounds Exception for allocated buffers if
88 * size() <= position() + new DWord().getLength().
89 * Method returns this to be used in command chaining.
90 *
91 * @param source value to write to buffer
92 * @return this
93 */
94 public abstract OscarByteBuffer write(ByteBased source);
95
96 /*** Writes a byte value at current position. This may throw an
97 * ArrayIndexOutOfBounds Exception for allocated buffers if
98 * size() <= position() + 1.
99 * Method returns this to be used in command chaining.
100 *
101 * @param source value to write to buffer
102 * @return this
103 */
104 public abstract OscarByteBuffer write(byte source);
105
106 /*** Writes a OscarByteBuffer value at current position. This may throw an
107 * ArrayIndexOutOfBounds Exception for allocated buffers if
108 * size() <= position() + source.slice().length().
109 * Method returns this to be used in command chaining.
110 *
111 * @param source value to write to buffer
112 * @return this
113 */
114 public abstract OscarByteBuffer write(OscarByteBuffer source);
115
116 /*** Returns the underlying data structure as byte array. This method
117 * does not clone the byte array nor tailor the length of the underlying byte
118 * array. Changes commited to this array will affect data in OscarByteBuffer.
119 * This method is considered to be more performant than slice().
120 *
121 * @return byte array
122 */
123 public abstract byte[] array();
124
125 /*** Returns the underlying data structure as byte array. This method
126 * returns a new instance of byte[] by calling Systen.arrayCopy or some
127 * other mechanism and tailor it's length to position()
128 *
129 * @return byte array
130 */
131 public abstract byte[] slice();
132
133 /*** Creates a new OscarByteBuffer instance that wraps the data byte[]
134 *
135 * @param data byte[] to wrap
136 * @return data wraped into OscarByteBuffer
137 */
138 public static OscarByteBuffer wrap(byte[] data) {
139 return new AllocatedByteBuffer(data);
140 }
141
142 /*** Allocates a static OscarByteBuffer with size size.
143 *
144 * @param size size of the new OscarByteBuffer
145 * @return OscarByteBuffer with size size
146 */
147 public static OscarByteBuffer allocate(int size) {
148 return new AllocatedByteBuffer(new byte[size]);
149 }
150
151 /*** Allocates a dynamic OscarByteBuffer. This Buffer will grow
152 * as you write data into it.
153 *
154 * @return OscarByteBuffer
155 */
156 public static OscarByteBuffer dynamic() {
157 return new DynamicByteBuffer();
158 }
159
160 /*** Allocates a dynamic OscarByteBuffer that wraps a byte[] and sets
161 * position() to data.length.
162 *
163 * @param data byte[] to wrap
164 * @return OscarByteBuffer
165 */
166 public static OscarByteBuffer wrapDynamic(byte[] data) {
167 return new DynamicByteBuffer(data);
168 }
169 }