wendover/README.in at develop · io7m-com/wendover · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104

## Repository Relocation

Development of this project has moved to an
[open-source but not open-contribution](https://sqlite.org/copyright.html#notopencontrib)
model.

Source code and commits will remain publicly available perpetually, but issues
and/or pull requests will be rejected and/or ignored. Additionally, this project
will now only be available via a read-only mirror at:

  https://codeberg.org/io7m-com/wendover


## wendover

The `wendover` package provides extra classes for working with Java NIO
channels.

## Features

* Numerous `Channel` classes and adapters with various properties.
* High coverage test suite.
* [OSGi-ready](https://www.osgi.org/).
* [JPMS-ready](https://en.wikipedia.org/wiki/Java_Platform_Module_System).
* ISC license.

## Usage

### CloseShieldSeekableByteChannel

Use `CloseShieldSeekableByteChannel` in order to prevent external code from
closing an arbitrary `SeekableByteChannel` instance:

```
SeekableByteChannel c;

someUntrustedObject.run(new CloseShieldSeekableByteChannel(c));
```

The `CloseShieldSeekableByteChannel` instance can be closed, but will not
result in the underlying channel really being closed.

### ReadOnlySeekableByteChannel

Use `ReadOnlySeekableByteChannel` to protect an arbitrary `SeekableByteChannel`
instance against writes:

```
SeekableByteChannel c;

someUntrustedObject.run(new ReadOnlySeekableByteChannel(c));
```

Attempts to write to the `ReadOnlySeekableByteChannel` will result in
`NonWritableChannelException` being thrown.

### SubrangeSeekableByteChannel

Use `SubrangeSeekableByteChannel` to restrict reads and writes to an arbitrary
`SeekableByteChannel` instance to a particular range:

```
SeekableByteChannel c;

someObject.run(new SubrangeSeekableByteChannel(c, 100L, 1000L));
```

Reads of the `SubrangeSeekableByteChannel` instance will be limited to only
reading data that falls within offsets `[100, 100 + 1000 - 1]`. Reading at
position `0` of the `SubrangeSeekableByteChannel` instance will actually
read from position `100` of `c`. Writes are similarly translated and limited.

### UpperRangeTrackingSeekableByteChannel

Use `UpperRangeTrackingSeekableByteChannel` to track the uppermost point
written by an arbitrary `SeekableByteChannel` instance:

```
SeekableByteChannel c;

var d = new UpperRangeTrackingSeekableByteChannel(c);

someObject.run(d);

System.out.println(d.uppermostWritten());
```

### ByteBufferChannels

Use the `ByteBufferChannels` class to adapt a `ByteBuffer` into a
`SeekableByteChannel`:

```
ByteBuffer data;

SeekableByteChannel c = ByteBufferChannels.ofByteBuffer(data);
```

### DelegatingSeekableByteChannel

Use the `DelegatingSeekableByteChannel` class to delegate operations to an
existing channel. This class is used to implement most of the `wendover`
package.