Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ttulka/boundary-io-streams

Boundary I/O Streams Java Library
https://github.com/ttulka/boundary-io-streams

boundary boundary-stream input-output io java java-library stream stream-processing streaming

Last synced: about 1 month ago
JSON representation

Boundary I/O Streams Java Library

Awesome Lists containing this project

README 

        
# Boundary I/O Streams



**Java library for boundary I/O streams.**



- Separate sub-stream from one stream with a boundary.

- Read multiple sub-stream from one stream based on a boundary.



A stream

```

+-------------------+----------+-----+-------------------+----------+----+

| sub-stream 1 data | boundary | ... | sub-stream N data | boundary | -1 |  

+-------------------+----------+-----+-------------------+----------+----+

```

will be read as

```

+-------------------+----+-----+-------------------+----+

| sub-stream 1 data | -1 | ... | sub-stream N data | -1 | finished 

+-------------------+----+-----+-------------------+----+

```



Please note the last boundary is not necessary but recommended for a good streaming design.



## Prerequisites

- Java 6



## Usage



Copy the Maven dependency into your Maven project:

```xml



    cz.net21.ttulka.io

    boundary-io-streams

    1.2.0



```



### Read from a Boundary Stream



#### Create a boundary input stream:

```java

BoundaryInputStream bis = null;

try {

    // create the bis from a file input stream

    FileInputStream fis = new FileInputStream("test.dat");

    bis = new BoundaryInputStream(fis);  // or new BoundaryInputStream(fis, boundary) with an explicit boundary

    // ...



} finally {

    // closes the base 'fis' automatically

    bis.close();

}

```



#### Iterate through multiple streams:

```java

for (InputStream is : bis) {

    int b;

    while ((b = is.read()) != -1) {

        // ...

    }

}

```



#### Use the multiple stream iterator:

```java

Iterator it = bis.iterator();

if (it.hasNext()) {

    InputStream is = it.next();

    

    int b;

    while ((b = is.read()) != -1) {

        // ...

    }

}

```



#### Alternatively you can work with the boundary input stream directly:

```java

while (!bis.hasFinished()) {

    bis.next();

    

    int b;

    while ((b = bis.read()) != -1) {

        // ...

    }

}

```



### Write into a Boundary Stream



#### Create a boundary output stream:

```java

BoundaryOutputStream bos = null;

try {

    // create the bos from a file output stream 

    FileOutputStream fos = new FileOutputStream("test.dat");

    bos = new BoundaryOutputStream(fos);  // or 'new BoundaryOutputStream(fos, boundary)' with an explicit boundary  

    // ...



} finally {

    // closes the base 'fos' automatically

    bos.close();

}

```



#### Write multiple streams into a boundary output stream:

```java

byte[] subStream1 = ...

bos.write(subStream1);

bos.boundary(); // write the boundary after the first sub-stream



byte[] subStream2 = ...

bos.write(subStream2);

bos.boundary(); // write the boundary after the second sub-stream

```



Method `boundary()` is only convenient and identical to the following code:

```java

byte[] boundary = ...

os.write(boundary);

```

So it's not necessary to create the stream via `BoundaryOutputStream` for reading it via `BoundaryInputStream`.



### Stop Boundary Stream



To stop consuming a stream after a boundary was reached it is possible to use the `StopBoundaryInputStream` class and the convenience class `StopBoundaryOutputStream` to generate such a stream.

The stop boundary streaming is still using a boundary to separate sub-streams, but when a stop boundary occurs the rest of the input stream is ignored.



The manner of work is same as with `BoundaryInputStream`, resp. `BoundaryOutputStream`.



#### Example:

```java

String[] values = {

        "abcde", "ABCDE", "12345"

};



byte[] boundary = "|".getBytes();

byte[] stopBoundary = "#".getBytes();



ByteArrayOutputStream bytes = new ByteArrayOutputStream();



StopBoundaryOutputStream out = new StopBoundaryOutputStream(bytes, boundary, stopBoundary);



for (String s : values) {

    out.write(s.getBytes());

    out.boundary();

}

out.stopBoundary();

out.write("xyz".getBytes());    // some junk at the end



//System.out.println(bytes);    // prints `abcde|ABCDE|12345|#xyz`



StopBoundaryInputStream in = new StopBoundaryInputStream(

        new ByteArrayInputStream(bytes.toByteArray()), boundary, stopBoundary);



for (InputStream is : in) {

    int b;

    while ((b = is.read()) != -1) {

        System.out.print((char) b);

    }

    System.out.println();

}



// close streams...

```

The code above prints:

```

abcde

ABCDE

12345

```

The last string `xyz` is ignored after the stop boundary was reached.



## Release Changes



### 1.2.0

- `StopBoundaryInputStream` and `StopBoundaryOutputStream` classes added.



### 1.1.0

- `BoundaryInputStream` implements `Iterable`.

- `IterableBoundaryInputStream` class removed as obsolete.

- Bugfix: `hasFinished() == true` after calling `close()`.



### 1.0.0

Initial version



## License



[Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)