Library: XBUP-core
Core library provides set of interfaces and functions to support handling of the XBUP-encoded documents. It provides basic parsers, declarations and catalog access, basic types and support for serialization, streaming and remote procedure calls (RPC).
Basic Interfaces
Library contains interfaces for document, block and type declarations.
Declarations
Declarations are included in “org.xbup.lib.core.block” package and subpackages. It's categorized by:
- Declaration or definition - Suffix Decl or Def
- Catalog or local related - Prefix XBC or XBD
Basic Types
There are types related to unary-binary encoding stored in “org.xbup.lib.core.ubnumber” package, which provides values storage and are implementing UBStreamable interface:
public int toStreamUB(OutputStream stream) public int fromStreamUB(InputStream stream) public int getSizeUB()
In package “org.xbup.lib.core.type” there are some additional classes for various other types.
Parsers
Implementation of pull and event parsers is included in core library in “org.xbup.lib.core.parser” package.
Basic Parser
Basic parsers use wide interface XBListener for level 0 which provides single method for each token type.
public void begin(XBBlockTerminationMode terminationMode) public void attrib(UBNatural attribute) public void data(InputStream data) public void end()
For level 1, there is similar interface XBTListener, which also includes additional method for type:
public void typeXBT(XBBlockType blockType)
Usage Examples
- Writting single node to file
try (XBListenerWriter writer = new XBListenerWriter()) { writer.open(new FileOutputStream("test.xb")); writer.beginXB(XBBlockTerminationMode.SIZE_SPECIFIED); writer.attribXB(new UBNat32(1)); writer.attribXB(new UBNat32(2)); writer.endXB(); writer.closeXB(); } catch (IOException | XBProcessingException ex) { // Process exception }
- Reading from file
try { XBProducerReader reader = new XBProducerReader(); reader.open(new FileInputStream("test.xb")); reader.attachXBListener(new XBListener() { @Override public void beginXB(XBBlockTerminationMode terminationMode) throws XBProcessingException, IOException { // Process your data } @Override public void attribXB(UBNatural attribute) throws XBProcessingException, IOException { // Process your data } @Override public void dataXB(InputStream data) throws XBProcessingException, IOException { // Process your data } @Override public void endXB() throws XBProcessingException, IOException { // Process your data } }); reader.read(); reader.close(); } catch (IOException | XBProcessingException ex) { // Process exception }
Token Parsers
Variant of parsing using tokens is defined in “org.xbup.lib.core.parser.token” package and provides interfaces with single method handing token value.
- For level 0 (XBToken):
XBBeginToken, XBAttributeToken, XBDataToken, XBEndToken
- For level 1 (XBTToken):
XBTBeginToken, XBTTypeToken, XBTAttributeToken, XBTDataToken, XBTEndToken
You have to process content of data token (for example read InputStream) before receiving next token.
For different ways and directions of handling tokens there are defined interfaces for each case:
- XBTEventListener - token stream goes into class and is controlled by sender
- XBTEventProducer - token stream goes from class and is controlled by sender
- XBTPullConsumer - token stream goes into class and is controlled by receiver
- XBTPullProvider - token stream goes from class and is controlled by receiver
And for conversion of binary data to token stream there are corresponding parser classes:
- XBTEventReader - binary stream to token stream controlled by sender
- XBTEventWriter - token stream to binary stream controlled by sender
- XBTPullReader - binary stream to token stream controlled by receiver
- XBTPullWriter - token stream to binary stream controlled by receiver
Usage Examples
- Writting single node to file
try (XBEventWriter writer = new XBEventWriter()) { writer.open(new FileOutputStream("test.xb")); writer.putXBToken(new XBBeginToken(XBBlockTerminationMode.SIZE_SPECIFIED)); writer.putXBToken(new XBAttributeToken(new UBNat32(1))); writer.putXBToken(new XBAttributeToken(new UBNat32(2))); writer.putXBToken(new XBEndToken()); writer.closeXB(); } catch (IOException | XBProcessingException ex) { // Process exception }
- Reading single node from file
try { XBPullReader reader = new XBPullReader(); reader.open(new FileInputStream("test.xb")); XBBeginToken beginToken = (XBBeginToken) reader.pullXBToken(); XBAttributeToken attribute1Token = (XBAttributeToken) reader.pullXBToken(); XBAttributeToken attribute2Token = (XBAttributeToken) reader.pullXBToken(); XBEndToken endToken = (XBEndToken) reader.pullXBToken(); } catch (IOException | XBProcessingException ex) { // Process exception }
Serialization
Several ways how to perform conversion of object data to protocol and in oposite direction are included in “org.xbup.lib.core.serial” package.
There are few subpackages covering various serialization methods:
- basic - Serializations using basic parser
- token - Serializations using token parser
- child - Serialization allowing include other serialized object as child blocks
- param - Serialization utilizing block specification and parameters
Streaming