FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

Adding JavaDoc - part 2 · xyygithub/msgpack-java@e599910 · GitHub

/ msgpack-java Public
forked from msgpack/msgpack-java

Commit e599910

Browse files
frsyuki
committed
Adding JavaDoc - part 2
1 parent 5228c5c commit e599910

33 files changed

Lines changed: 279 additions & 53 deletions

‎msgpack-core/src/main/java/org/msgpack/core/MessageBufferPacker.java‎

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,11 @@
2323
import java.util.List;
2424

2525
/**
26-
* MessagePacker that is useful to produce byte array output
26+
* MessagePacker that is useful to produce byte array output.
27+
* <p>
28+
* This class allocates a new buffer instead of resizing the buffer when data doesn't fit in the initial capacity.
29+
* This is faster than ByteArrayOutputStream especially when size of written bytes is large because resizing a buffer
30+
* usually needs to copy contents of the buffer.
2731
*/
2832
public class MessageBufferPacker
2933
extends MessagePacker
@@ -52,11 +56,22 @@ private ArrayBufferOutput getArrayBufferOut()
5256
return (ArrayBufferOutput) out;
5357
}
5458

59+
/**
60+
* Clears the written data.
61+
*/
5562
public void clear()
5663
{
5764
getArrayBufferOut().clear();
5865
}
5966

67+
/**
68+
* Gets copy of the written data as a byte array.
69+
* <p>
70+
* If your application needs better performance and smaller memory consumption, you may prefer
71+
* {@link #toMessageBuffer()} or {@link #toBufferList()} to avoid copying.
72+
*
73+
* @return the byte array
74+
*/
6075
public byte[] toByteArray()
6176
{
6277
try {
@@ -69,6 +84,14 @@ public byte[] toByteArray()
6984
return getArrayBufferOut().toByteArray();
7085
}
7186

87+
/**
88+
* Gets the written data as a MessageBuffer.
89+
* <p>
90+
* Unlike {@link #toByteArray()}, this method omits copy of the contents if size of the written data is smaller
91+
* than a single buffer capacity.
92+
*
93+
* @return the MessageBuffer instance
94+
*/
7295
public MessageBuffer toMessageBuffer()
7396
{
7497
try {
@@ -81,6 +104,14 @@ public MessageBuffer toMessageBuffer()
81104
return getArrayBufferOut().toMessageBuffer();
82105
}
83106

107+
/**
108+
* Returns the written data as a list of MessageBuffer.
109+
* <p>
110+
* Unlike {@link #toByteArray()} or {@link #toMessageBuffer()}, this is the fastest method that doesn't
111+
* copy contents in any cases.
112+
*
113+
* @return the list of MessageBuffer instances
114+
*/
84115
public List<MessageBuffer> toBufferList()
85116
{
86117
try {

‎msgpack-core/src/main/java/org/msgpack/core/MessagePack.java‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@
3535
/**
3636
* Convenience class to build packer and unpacker classes.
3737
*
38-
* You may choose factory method as following
38+
* You can select an appropriate factory method as following.
3939
*
4040
* <p>
4141
* Deserializing objects from binary:
@@ -70,12 +70,12 @@ public class MessagePack
7070
public static final Charset UTF8 = Charset.forName("UTF-8");
7171

7272
/**
73-
* Configuration of a {@link MessagePacker} created by {@link #newDefaultPacker(MessageBufferOutput)} and {@link #newDefaultBufferPacker()} methods.
73+
* Configuration of a {@link MessagePacker} used by {@link #newDefaultPacker(MessageBufferOutput)} and {@link #newDefaultBufferPacker()} methods.
7474
*/
7575
public static final PackerConfig DEFAULT_PACKER_CONFIG = new PackerConfig();
7676

7777
/**
78-
* Configuration of a {@link MessageUnpacker} created by {@link #newDefaultUnpacker(MessageBufferInput)} methods.
78+
* Configuration of a {@link MessageUnpacker} used by {@link #newDefaultUnpacker(MessageBufferInput)} methods.
7979
*/
8080
public static final UnpackerConfig DEFAULT_UNPACKER_CONFIG = new UnpackerConfig();
8181

‎msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@
7272
* an instance.
7373
* <p>
7474
* This class provides following primitive methods to write MessagePack values. These primitive methods write
75-
* short bytes (1 to 7 bytes) to the internal buffer at once. There also some complex methods for convenience.
75+
* short bytes (1 to 7 bytes) to the internal buffer at once. There are also some complex methods for convenience.
7676
* <p>
7777
* Primitive methods:
7878
*
@@ -110,13 +110,13 @@
110110
*
111111
* <p>
112112
* To write a List, Collection or array, first you call {@link #packArrayHeader(int)} method with the number of
113-
* elements. Then, you call packer methods for each element. You don't have to call anything at the end of
113+
* elements. Then, you call packer methods for each element.
114114
* iteration.
115115
*
116116
* <p>
117117
* To write a Map, first you call {@link #packMapHeader(int)} method with size of the map. Then, for each pair,
118118
* you call packer methods for key first, and then value. You will call packer methods twice as many time as the
119-
* size of the map. You don't have to call anything at the end of iteration.
119+
* size of the map.
120120
*
121121
* <p>
122122
* Note that packXxxHeader methods don't validate number of elements. You must call packer methods for correct

‎msgpack-core/src/main/java/org/msgpack/core/MessageUnpacker.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -139,12 +139,12 @@
139139
*
140140
* <p>
141141
* To read an Array type, first you call {@link #unpackArrayHeader()} method to get number of elements. Then,
142-
* you call unpacker methods for each element. You don't have to call anything at the end of iteration.
142+
* you call unpacker methods for each element.
143143
*
144144
* <p>
145145
* To read a Map, first you call {@link #unpackMapHeader(int)} method to get number of pairs of the map. Then,
146146
* for each pair, you call unpacker methods for key first, and then value. You will call unpacker methods twice
147-
* as many time as the returned count. You don't have to call anything at the end of iteration.
147+
* as many time as the returned count.
148148
*
149149
*/
150150
public class MessageUnpacker

‎msgpack-core/src/main/java/org/msgpack/core/buffer/ArrayBufferOutput.java‎

Lines changed: 35 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,11 @@
1919
import java.util.ArrayList;
2020

2121
/**
22-
* MessageBufferOutput adapter that packs data into list of byte arrays.
22+
* MessageBufferOutput adapter that writes data into a list of byte arrays.
23+
* <p>
24+
* This class allocates a new buffer instead of resizing the buffer when data doesn't fit in the initial capacity.
25+
* This is faster than ByteArrayOutputStream especially when size of written bytes is large because resizing a buffer
26+
* usually needs to copy contents of the buffer.
2327
*/
2428
public class ArrayBufferOutput
2529
implements MessageBufferOutput
@@ -39,6 +43,11 @@ public ArrayBufferOutput(int bufferSize)
3943
this.list = new ArrayList<MessageBuffer>();
4044
}
4145

46+
/**
47+
* Gets size of the written data.
48+
*
49+
* @return number of bytes
50+
*/
4251
public int getSize()
4352
{
4453
int size = 0;
@@ -48,6 +57,14 @@ public int getSize()
4857
return size;
4958
}
5059

60+
/**
61+
* Gets copy of the written data as a byte array.
62+
* <p>
63+
* If your application needs better performance and smaller memory consumption, you may prefer
64+
* {@link #toMessageBuffer()} or {@link #toBufferList()} to avoid copying.
65+
*
66+
* @return the byte array
67+
*/
5168
public byte[] toByteArray()
5269
{
5370
byte[] data = new byte[getSize()];
@@ -59,6 +76,14 @@ public byte[] toByteArray()
5976
return data;
6077
}
6178

79+
/**
80+
* Gets the written data as a MessageBuffer.
81+
* <p>
82+
* Unlike {@link #toByteArray()}, this method omits copy of the contents if size of the written data is smaller
83+
* than a single buffer capacity.
84+
*
85+
* @return the MessageBuffer instance
86+
*/
6287
public MessageBuffer toMessageBuffer()
6388
{
6489
if (list.size() == 1) {
@@ -72,13 +97,21 @@ else if (list.isEmpty()) {
7297
}
7398
}
7499

100+
/**
101+
* Returns the written data as a list of MessageBuffer.
102+
* <p>
103+
* Unlike {@link #toByteArray()} or {@link #toMessageBuffer()}, this is the fastest method that doesn't
104+
* copy contents in any cases.
105+
*
106+
* @return the list of MessageBuffer instances
107+
*/
75108
public List<MessageBuffer> toBufferList()
76109
{
77110
return new ArrayList<MessageBuffer>(list);
78111
}
79112

80113
/**
81-
* Clears the internal buffers
114+
* Clears the written data.
82115
*/
83116
public void clear()
84117
{

‎msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBuffer.java‎

Lines changed: 15 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -28,12 +28,20 @@
2828
import static org.msgpack.core.Preconditions.checkNotNull;
2929

3030
/**
31-
* MessageBuffer class is an abstraction of memory for reading/writing message packed data.
32-
* This MessageBuffers ensures short/int/float/long/double values are written in the big-endian order.
33-
* <p/>
34-
* This class is optimized for fast memory access, so many methods are
35-
* implemented without using any interface method that produces invokeinterface call in JVM.
36-
* Compared to invokevirtual, invokeinterface is 30% slower in general because it needs to find a target function from the table.
31+
* MessageBuffer class is an abstraction of memory with fast methods to serialize and deserialize primitive values
32+
* to/from the memory. All MessageBuffer implementations ensure short/int/float/long/double values are written in
33+
* big-endian order.
34+
* <p>
35+
* Applications can allocate a new buffer using {@link #allocate(int)} method, or wrap an byte array or ByteBuffer
36+
* using {@link wrap(byte[], int, int)} methods. {@link wrap(ByteBuffer)} method supports both direct buffers and
37+
* array-backed buffers.
38+
* <p>
39+
* MessageBuffer class itself is optimized for little-endian CPU archtectures so that JVM (HotSpot) can take advantage
40+
* of the fastest JIT format which skips TypeProfile checking. To ensure this performance, applications must not load
41+
* unnecessary classes such as MessagePackBE. On big-endian CPU archtectures, implementation uses subclass that
42+
* includes TypeProfile overhead but still faster than ByteBuffer. On JVMs older than Java 7 and JVMs without Unsafe
43+
* API (such as Android), implementation falls back to a universal implementation that uses standard ByteBuffer class
44+
* internally.
3745
*/
3846
public class MessageBuffer
3947
{
@@ -69,8 +77,7 @@ public class MessageBuffer
6977
try {
7078
int major = Integer.parseInt(javaVersion.substring(0, dotPos));
7179
int minor = Integer.parseInt(javaVersion.substring(dotPos + 1));
72-
isJavaAtLeast7 = major > 1 || (major == 1 && minor >= 7);
73-
}
80+
isJavaAtLeast7 = major > 1 || (major == 1 && minor >= 7); }
7481
catch (NumberFormatException e) {
7582
e.printStackTrace(System.err);
7683
}

‎msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferInput.java‎

Lines changed: 23 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,19 +19,38 @@
1919
import java.io.IOException;
2020

2121
/**
22-
* Provides a sequence of MessageBuffers that contains message packed data.
22+
* Provides a sequence of MessageBuffer instances.
23+
*
24+
* A MessageBufferInput implementation has control of lifecycle of the memory so that it can reuse previously
25+
* allocated memory, use memory pools, or use memory-mapped files.
2326
*/
2427
public interface MessageBufferInput
2528
extends Closeable
2629
{
2730
/**
28-
* Get a next buffer to read.
31+
* Returns a next buffer to read.
2932
* <p>
30-
* When this method is called, the formally allocated buffer can be safely discarded.
33+
* This method should return a MessageBuffer instance that has data filled in. When this method is called twice,
34+
* the previously returned buffer is no longer used. Thus implementation of this method can safely discard it.
35+
* This is useful when it uses a memory pool.
3136
*
3237
* @return the next MessageBuffer, or return null if no more buffer is available.
33-
* @throws IOException when error occurred when reading the data
38+
* @throws IOException when IO error occurred when reading the data
3439
*/
3540
MessageBuffer next()
3641
throws IOException;
42+
43+
/**
44+
* Closes the input.
45+
* <p>
46+
* When this method is called, the buffer previously returned from {@link next()} method is no longer used.
47+
* Thus implementation of this method can safely discard it.
48+
* <p>
49+
* If the input is already closed then invoking this method has no effect.
50+
*
51+
* @throws IOException when IO error occurred when closing the data source
52+
*/
53+
@Override
54+
void close()
55+
throws IOException;
3756
}

‎msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferOutput.java‎

Lines changed: 24 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -20,29 +20,40 @@
2020
import java.io.Flushable;
2121

2222
/**
23-
* Provides a buffered output stream for packing objects
23+
* Provides a buffered output stream that writes sequence of MessageBuffer instances.
24+
*
25+
* A MessageBufferOutput implementation has total control of the buffer memory so that it can reuse buffer memory,
26+
* use buffer pools, or use memory-mapped files.
2427
*/
2528
public interface MessageBufferOutput
2629
extends Closeable, Flushable
2730
{
2831
/**
29-
* Allocates the next buffer for writing message packed data.
30-
* If the previously allocated buffer is not flushed yet, this next method should discard
31-
* it without writing it.
32+
* Allocates the next buffer to write.
33+
* <p>
34+
* This method should return a MessageBuffer instance that has at least specified size of capacity.
35+
* <p>
36+
* When this method is called twice, the previously returned buffer is no longer used. This method may be called
37+
* twice without call of {@link writeBuffer(MessageBuffer)} in between. In this case, the buffer should be
38+
* discarded without flushing it to the output.
3239
*
3340
* @param minimumSize the mimium required buffer size to allocate
34-
* @return
41+
* @return the MessageBuffer instance with at least minimumSize bytes of capacity
3542
* @throws IOException
3643
*/
3744
MessageBuffer next(int minimumSize)
3845
throws IOException;
3946

4047
/**
41-
* Flushes the previously allocated buffer.
42-
* This method is not always called because next method also flushes previously allocated buffer.
43-
* This method is called when write method is called or application wants to control the timing of flush.
48+
* Writes the previously allocated buffer.
49+
* <p>
50+
* This method should write the buffer previously returned from {@link next(int)} method until specified number of
51+
* bytes. Once the buffer is written, the buffer is no longer used.
52+
* <p>
53+
* This method is not always called for each {@link next(int)} call. In this case, the buffer should be discarded
54+
* without flushing it to the output.
4455
*
45-
* @param length the size of buffer to flush
56+
* @param length the number of bytes to write
4657
* @throws IOException
4758
*/
4859
void writeBuffer(int length)
@@ -63,7 +74,10 @@ void write(byte[] buffer, int offset, int length)
6374

6475
/**
6576
* Writes an external payload data.
66-
* This buffer is given - this MessageBufferOutput owns the buffer and may modify contents of the buffer. Contents of this buffer won't be modified by the caller.
77+
* <p>
78+
* Unlike {@link #write(byte[], int, int)} method, the buffer is given - this MessageBufferOutput implementation
79+
* gets ownership of the buffer and may modify contents of the buffer. Contents of this buffer won't be modified
80+
* by the caller.
6781
*
6882
* @param buffer the data to add
6983
* @param offset the start offset in the data

‎msgpack-core/src/main/java/org/msgpack/value/ArrayValue.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919
import java.util.List;
2020

2121
/**
22-
* The interface {@code ArrayValue} represents MessagePack's Array type.
22+
* Representation of MessagePack's Array type.
2323
*
2424
* MessagePack's Array type can represent sequence of values.
2525
*/

‎msgpack-core/src/main/java/org/msgpack/value/BinaryValue.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
package org.msgpack.value;
1717

1818
/**
19-
* The interface {@code BinaryValue} represents MessagePack's Binary type.
19+
* Representation of MessagePack's Binary type.
2020
*
2121
* MessagePack's Binary type can represent a byte array at most 2<sup>64</sup>-1 bytes.
2222
*

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL