XBUP - eXtensible Binary Universal Protocol - Documentation
[Up]

# XBUP Core Library (Java)

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

### Stream Event Processing

## Framework and Catalog Access

Homepage: http://xbup.org
License: GNU Free Documentation License (FDL)