Skip to content

Commit e664ebc

Browse files
mjpt777mjpt777
committed
[Java] Add Javadoc for IR.
1 parent 3001874 commit e664ebc

13 files changed

+134
-36
lines changed

‎sbe-tool/src/main/java/uk/co/real_logic/sbe/ir/HeaderStructure.java‎

Lines changed: 56 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,8 @@
2121
import java.util.List;
2222

2323
/**
24-
* Metadata description for a message headerStructure
24+
* Metadata description for a message header structure expected before messages to understand the type requiring
25+
* decoding.
2526
*/
2627
public class HeaderStructure
2728
{
@@ -36,6 +37,10 @@ public class HeaderStructure
3637
private PrimitiveType schemaIdType;
3738
private PrimitiveType schemaVersionType;
3839

40+
/**
41+
* Construct the header structure from a list of tokens containing the minimum expected set of fields.
42+
* @param tokens for the header structure.
43+
*/
3944
public HeaderStructure(final List<Token> tokens)
4045
{
4146
Verify.notNull(tokens, "tokens");
@@ -49,53 +54,78 @@ public HeaderStructure(final List<Token> tokens)
4954
Verify.notNull(schemaVersionType, "schemaVersionType");
5055
}
5156

52-
private void captureEncodings(final List<Token> tokens)
53-
{
54-
for (final Token token : tokens)
55-
{
56-
switch (token.name())
57-
{
58-
case BLOCK_LENGTH:
59-
blockLengthType = token.encoding().primitiveType();
60-
break;
61-
62-
case TEMPLATE_ID:
63-
templateIdType = token.encoding().primitiveType();
64-
break;
65-
66-
case SCHEMA_ID:
67-
schemaIdType = token.encoding().primitiveType();
68-
break;
69-
70-
case SCHEMA_VERSION:
71-
schemaVersionType = token.encoding().primitiveType();
72-
break;
73-
}
74-
}
75-
}
76-
57+
/**
58+
* The IR tokens for the header.
59+
*
60+
* @return the IR tokens for the header.
61+
*/
7762
public List<Token> tokens()
7863
{
7964
return tokens;
8065
}
8166

67+
/**
68+
* The declared data type for the block length field.
69+
*
70+
* @return the declared data type for the block length field.
71+
*/
8272
public PrimitiveType blockLengthType()
8373
{
8474
return blockLengthType;
8575
}
8676

77+
/**
78+
* The declared data type for the template id field.
79+
*
80+
* @return the declared data type for the template id field.
81+
*/
8782
public PrimitiveType templateIdType()
8883
{
8984
return templateIdType;
9085
}
9186

87+
/**
88+
* The declared data type for the SBE schema id field.
89+
*
90+
* @return the declared data type for the SBE schema id field.
91+
*/
9292
public PrimitiveType schemaIdType()
9393
{
9494
return schemaIdType;
9595
}
9696

97+
/**
98+
* The declared data type for the SBE schema version field.
99+
*
100+
* @return the declared data type for the SBE schema version field.
101+
*/
97102
public PrimitiveType schemaVersionType()
98103
{
99104
return schemaVersionType;
100105
}
106+
107+
private void captureEncodings(final List<Token> tokens)
108+
{
109+
for (final Token token : tokens)
110+
{
111+
switch (token.name())
112+
{
113+
case BLOCK_LENGTH:
114+
blockLengthType = token.encoding().primitiveType();
115+
break;
116+
117+
case TEMPLATE_ID:
118+
templateIdType = token.encoding().primitiveType();
119+
break;
120+
121+
case SCHEMA_ID:
122+
schemaIdType = token.encoding().primitiveType();
123+
break;
124+
125+
case SCHEMA_VERSION:
126+
schemaVersionType = token.encoding().primitiveType();
127+
break;
128+
}
129+
}
130+
}
101131
}

‎sbe-tool/src/main/java/uk/co/real_logic/sbe/ir/IrDecoder.java‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,9 @@
3434
import static java.nio.file.StandardOpenOption.READ;
3535
import static uk.co.real_logic.sbe.ir.IrUtil.*;
3636

37+
/**
38+
* Decoder for encoded {@link Ir} representing an SBE schema which can be read from a buffer or file.
39+
*/
3740
public class IrDecoder implements AutoCloseable
3841
{
3942
private static final int CAPACITY = 4096;
@@ -53,6 +56,11 @@ public class IrDecoder implements AutoCloseable
5356
private final byte[] valArray = new byte[CAPACITY];
5457
private final MutableDirectBuffer valBuffer = new UnsafeBuffer(valArray);
5558

59+
/**
60+
* Construct a {@link Ir} decoder by opening a file for a given name.
61+
*
62+
* @param fileName containing the encoded {@link Ir}.
63+
*/
5664
public IrDecoder(final String fileName)
5765
{
5866
try
@@ -70,6 +78,11 @@ public IrDecoder(final String fileName)
7078
}
7179
}
7280

81+
/**
82+
* Construct a {@link Ir} decoder for data encoded in a {@link ByteBuffer}.
83+
*
84+
* @param buffer containing the serialised {@link Ir}.
85+
*/
7386
public IrDecoder(final ByteBuffer buffer)
7487
{
7588
channel = null;
@@ -78,11 +91,19 @@ public IrDecoder(final ByteBuffer buffer)
7891
offset = 0;
7992
}
8093

94+
/**
95+
* {@inheritDoc}
96+
*/
8197
public void close()
8298
{
8399
CloseHelper.quietClose(channel);
84100
}
85101

102+
/**
103+
* Decode the serialised {@link Ir} and return the decoded instance.
104+
*
105+
* @return the decoded serialised {@link Ir} instance.
106+
*/
86107
public Ir decode()
87108
{
88109
decodeFrame();

‎sbe-tool/src/main/java/uk/co/real_logic/sbe/ir/IrEncoder.java‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,9 @@
3939
import static uk.co.real_logic.sbe.ir.generated.FrameCodecEncoder.semanticVersionCharacterEncoding;
4040
import static uk.co.real_logic.sbe.ir.generated.TokenCodecEncoder.*;
4141

42+
/**
43+
* Encoder for {@link Ir} representing an SBE schema which can be written to a buffer or file.
44+
*/
4245
public class IrEncoder implements AutoCloseable
4346
{
4447
private static final int CAPACITY = 4096;
@@ -54,6 +57,12 @@ public class IrEncoder implements AutoCloseable
5457
private final UnsafeBuffer valBuffer = new UnsafeBuffer(valArray);
5558
private int totalLength = 0;
5659

60+
/**
61+
* Construct an encoder for {@link Ir} to a file. An existing file will be overwritten.
62+
*
63+
* @param fileName into which the {@link Ir} will be encoded.
64+
* @param ir to be encoded into the file.
65+
*/
5766
public IrEncoder(final String fileName, final Ir ir)
5867
{
5968
try
@@ -71,6 +80,12 @@ public IrEncoder(final String fileName, final Ir ir)
7180
}
7281
}
7382

83+
/**
84+
* Construct an encoder for {@link Ir} to a {@link ByteBuffer}.
85+
*
86+
* @param buffer into which the {@link Ir} will be encoded.
87+
* @param ir to be encoded into the buffer.
88+
*/
7489
public IrEncoder(final ByteBuffer buffer, final Ir ir)
7590
{
7691
channel = null;
@@ -80,11 +95,19 @@ public IrEncoder(final ByteBuffer buffer, final Ir ir)
8095
this.ir = ir;
8196
}
8297

98+
/**
99+
* {@inheritDoc}
100+
*/
83101
public void close()
84102
{
85103
CloseHelper.quietClose(channel);
86104
}
87105

106+
/**
107+
* Encode the provided {@link Ir} and return the length in bytes encoded.
108+
*
109+
* @return encode the provided {@link Ir} and return the length in bytes encoded.
110+
*/
88111
public int encode()
89112
{
90113
Verify.notNull(ir, "ir");

‎sbe-tool/src/main/java/uk/co/real_logic/sbe/ir/IrUtil.java‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,9 @@
2727
import java.io.UnsupportedEncodingException;
2828
import java.nio.ByteOrder;
2929

30+
/**
31+
* Utility functions for working with {@link Ir}.
32+
*/
3033
public class IrUtil
3134
{
3235
public static final byte[] EMPTY_BUFFER = new byte[0];

‎sbe-tool/src/main/java/uk/co/real_logic/sbe/ir/MessageComponents.java‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,9 @@
1919
import java.util.Collections;
2020
import java.util.List;
2121

22+
/**
23+
* Collect the message components (fields, groups, data) to help with generating codecs.
24+
*/
2225
public class MessageComponents
2326
{
2427
public final Token messageToken;

‎sbe-tool/src/main/java/uk/co/real_logic/sbe/ir/generated/ByteOrderCodec.java‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
/* Generated SBE (Simple Binary Encoding) message codec */
22
package uk.co.real_logic.sbe.ir.generated;
33

4+
/**
5+
* Number encoding byte order
6+
*/
47
public enum ByteOrderCodec
58
{
69
SBE_LITTLE_ENDIAN((short)0),

‎sbe-tool/src/main/java/uk/co/real_logic/sbe/ir/generated/PresenceCodec.java‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
/* Generated SBE (Simple Binary Encoding) message codec */
22
package uk.co.real_logic.sbe.ir.generated;
33

4+
/**
5+
* Field presence declaration
6+
*/
47
public enum PresenceCodec
58
{
69
SBE_REQUIRED((short)0),

‎sbe-tool/src/main/java/uk/co/real_logic/sbe/ir/generated/PrimitiveTypeCodec.java‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
/* Generated SBE (Simple Binary Encoding) message codec */
22
package uk.co.real_logic.sbe.ir.generated;
33

4+
/**
5+
* Primitive types in type system
6+
*/
47
public enum PrimitiveTypeCodec
58
{
69
NONE((short)0),

‎sbe-tool/src/main/java/uk/co/real_logic/sbe/ir/generated/SignalCodec.java‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
/* Generated SBE (Simple Binary Encoding) message codec */
22
package uk.co.real_logic.sbe.ir.generated;
33

4+
/**
5+
* Token signal type in IR
6+
*/
47
public enum SignalCodec
58
{
69
BEGIN_MESSAGE((short)1),

‎sbe-tool/src/main/java/uk/co/real_logic/sbe/ir/generated/TokenCodecDecoder.java‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1723,22 +1723,22 @@ public StringBuilder appendTo(final StringBuilder builder)
17231723
builder.append(componentTokenCount());
17241724
builder.append('|');
17251725
//Token{signal=BEGIN_FIELD, name='signal', referencedName='null', description='null', id=6, version=0, deprecated=0, encodedLength=1, offset=20, componentTokenCount=21, encoding=Encoding{presence=REQUIRED, primitiveType=null, byteOrder=LITTLE_ENDIAN, minValue=null, maxValue=null, nullValue=null, constValue=null, characterEncoding='null', epoch='null', timeUnit=null, semanticType='null'}}
1726-
//Token{signal=BEGIN_ENUM, name='SignalCodec', referencedName='null', description='null', id=-1, version=0, deprecated=0, encodedLength=1, offset=20, componentTokenCount=19, encoding=Encoding{presence=REQUIRED, primitiveType=UINT8, byteOrder=LITTLE_ENDIAN, minValue=null, maxValue=null, nullValue=null, constValue=null, characterEncoding='null', epoch='null', timeUnit=null, semanticType='null'}}
1726+
//Token{signal=BEGIN_ENUM, name='SignalCodec', referencedName='null', description='Token signal type in IR', id=-1, version=0, deprecated=0, encodedLength=1, offset=20, componentTokenCount=19, encoding=Encoding{presence=REQUIRED, primitiveType=UINT8, byteOrder=LITTLE_ENDIAN, minValue=null, maxValue=null, nullValue=null, constValue=null, characterEncoding='null', epoch='null', timeUnit=null, semanticType='null'}}
17271727
builder.append("signal=");
17281728
builder.append(signal());
17291729
builder.append('|');
17301730
//Token{signal=BEGIN_FIELD, name='primitiveType', referencedName='null', description='null', id=7, version=0, deprecated=0, encodedLength=1, offset=21, componentTokenCount=16, encoding=Encoding{presence=REQUIRED, primitiveType=null, byteOrder=LITTLE_ENDIAN, minValue=null, maxValue=null, nullValue=null, constValue=null, characterEncoding='null', epoch='null', timeUnit=null, semanticType='null'}}
1731-
//Token{signal=BEGIN_ENUM, name='PrimitiveTypeCodec', referencedName='null', description='null', id=-1, version=0, deprecated=0, encodedLength=1, offset=21, componentTokenCount=14, encoding=Encoding{presence=REQUIRED, primitiveType=UINT8, byteOrder=LITTLE_ENDIAN, minValue=null, maxValue=null, nullValue=null, constValue=null, characterEncoding='null', epoch='null', timeUnit=null, semanticType='null'}}
1731+
//Token{signal=BEGIN_ENUM, name='PrimitiveTypeCodec', referencedName='null', description='Primitive types in type system', id=-1, version=0, deprecated=0, encodedLength=1, offset=21, componentTokenCount=14, encoding=Encoding{presence=REQUIRED, primitiveType=UINT8, byteOrder=LITTLE_ENDIAN, minValue=null, maxValue=null, nullValue=null, constValue=null, characterEncoding='null', epoch='null', timeUnit=null, semanticType='null'}}
17321732
builder.append("primitiveType=");
17331733
builder.append(primitiveType());
17341734
builder.append('|');
17351735
//Token{signal=BEGIN_FIELD, name='byteOrder', referencedName='null', description='null', id=8, version=0, deprecated=0, encodedLength=1, offset=22, componentTokenCount=6, encoding=Encoding{presence=REQUIRED, primitiveType=null, byteOrder=LITTLE_ENDIAN, minValue=null, maxValue=null, nullValue=null, constValue=null, characterEncoding='null', epoch='null', timeUnit=null, semanticType='null'}}
1736-
//Token{signal=BEGIN_ENUM, name='ByteOrderCodec', referencedName='null', description='null', id=-1, version=0, deprecated=0, encodedLength=1, offset=22, componentTokenCount=4, encoding=Encoding{presence=REQUIRED, primitiveType=UINT8, byteOrder=LITTLE_ENDIAN, minValue=null, maxValue=null, nullValue=null, constValue=null, characterEncoding='null', epoch='null', timeUnit=null, semanticType='null'}}
1736+
//Token{signal=BEGIN_ENUM, name='ByteOrderCodec', referencedName='null', description='Number encoding byte order', id=-1, version=0, deprecated=0, encodedLength=1, offset=22, componentTokenCount=4, encoding=Encoding{presence=REQUIRED, primitiveType=UINT8, byteOrder=LITTLE_ENDIAN, minValue=null, maxValue=null, nullValue=null, constValue=null, characterEncoding='null', epoch='null', timeUnit=null, semanticType='null'}}
17371737
builder.append("byteOrder=");
17381738
builder.append(byteOrder());
17391739
builder.append('|');
17401740
//Token{signal=BEGIN_FIELD, name='presence', referencedName='null', description='null', id=9, version=0, deprecated=0, encodedLength=1, offset=23, componentTokenCount=7, encoding=Encoding{presence=REQUIRED, primitiveType=null, byteOrder=LITTLE_ENDIAN, minValue=null, maxValue=null, nullValue=null, constValue=null, characterEncoding='null', epoch='null', timeUnit=null, semanticType='null'}}
1741-
//Token{signal=BEGIN_ENUM, name='PresenceCodec', referencedName='null', description='null', id=-1, version=0, deprecated=0, encodedLength=1, offset=23, componentTokenCount=5, encoding=Encoding{presence=REQUIRED, primitiveType=UINT8, byteOrder=LITTLE_ENDIAN, minValue=null, maxValue=null, nullValue=null, constValue=null, characterEncoding='null', epoch='null', timeUnit=null, semanticType='null'}}
1741+
//Token{signal=BEGIN_ENUM, name='PresenceCodec', referencedName='null', description='Field presence declaration', id=-1, version=0, deprecated=0, encodedLength=1, offset=23, componentTokenCount=5, encoding=Encoding{presence=REQUIRED, primitiveType=UINT8, byteOrder=LITTLE_ENDIAN, minValue=null, maxValue=null, nullValue=null, constValue=null, characterEncoding='null', epoch='null', timeUnit=null, semanticType='null'}}
17421742
builder.append("presence=");
17431743
builder.append(presence());
17441744
builder.append('|');

0 commit comments

Comments
 (0)