diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 37 |
1 files changed, 26 insertions, 11 deletions
@@ -19,17 +19,32 @@ There are a bunch of reasons why NineKt was born: Usage ----- -The most important class is `NinePConnection`. This class translates file system operations (reading, writing, etc.) -into 9P network messages and vice versa. It needs basic information about: the connection details (remote host's -address, port, etc.), the file system handlers (functions for reading, writing, etc.), and network handlers (functions -for sending and receiving data in the networking scope). Connection details are provided directly to the class, while -handlers must be provided by implementing the `FileSystemManager` and `NetworkManager` interfaces. - -Avoiding using file system and networking primitives directly vastly improves independence from them (and therefore -portability), in addition to letting NineKt's codebase focus solely on the 9P protocol itself and the translation of one -set of operations into the other. - -Once everything is properly configured, the 9P connection can be started using the `connect` method. +The most important class, and also the only one you'll need for basic usage, is `NinePConnection`. This class implements +the 9P protocol on top of another unknown transport-layer protocol (although it's usually TCP) provided, and managed, by +a subclass of the `NetworkManager` abstract class. For this reason, the `NinePConnection`'s constructor requires an +instance of another class that implements `NetworkManager`. It doesn't need anything else. + +The `NetworkManager` class provides abstraction over the specific networking methods. This makes the classes using +`NetworkManager` independent from both the specific networking API and the underlying transport-layer protocol of +choice. This allows swapping the API or protocol at any time and vastly improves portability. With all this considered, +since Java's standard library provides a networking API already, I thought that an implementation based on that would be +imperative, appreciated, and especially broadly used. + +```kotlin +// This example uses one of the dial(2) formats for the address and port. +val npconn: NinePConnection +try { + npconn = NinePConnection(NetworkManagerJavaNet("net!9p.mydomain.com!564")) +} catch (uhe: UnresolvableHostException) { + // failed :( +} +``` + +While `NetworkManager` implementation initializes the transport-layer connection as soon as it's instanced, this is not +true for `NinePConnection` and the 9P connection. The reason why the 9P protocol is not immediately initialized is that +`NinePConnection` only exposes methods that coincide with the protocol messages, which means that providing an automated +way to initialize the protocol would mix two levels of abstraction in the same class. For this purpose, the `initNineP` +function is a shorthand that can do it for you, although it's possible to do so manually by using the 9P primitives. A word on Android ----------------- |