diff options
| -rw-r--r-- | README.md | 32 |
1 files changed, 19 insertions, 13 deletions
@@ -2,8 +2,13 @@ NineKt: Teaching Kotlin to speak 9P =================================== NineKt (I don't really care about pronunciation, "nine-kay-tee" or "nine-Kate" or whatever you want) is a library -written in Kotlin (and primarily targeting the JVM) that eases the process of implementing the [9P protocol](https://en.wikipedia.org/wiki/9P_(protocol)) -into any JVM application, including those for Android. +written in Kotlin (and primarily targeting the JVM) that provides a client-side implementation to the +[9P protocol](https://en.wikipedia.org/wiki/9P_(protocol)). It targets any JVM application, especially those that run on +Android. + +The implementation of client-side 9P provided by NineKt and the expected server-side behavior are those described by the +[section 5 in 9front's manual pages](https://man.9front.org/5/). All differences between this and the original Plan 9 +from Bell Labs specification, or any other specification (provided by, e.g., forks of it), are therefore ignored. Rationale --------- @@ -19,16 +24,16 @@ There are a bunch of reasons why NineKt was born: Usage ----- -The most important class, and also the only one you'll need for basic usage, is `NinePConnection`. This class implements +The most important class, and also the fulcrum of the entire implementation, 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 `NetworkPacketTransporter` abstract class. For this reason, the `NinePConnection`'s constructor requires an instance of another class that implements `NetworkPacketTransporter`. It doesn't need anything else. The `NetworkPacketTransporter` class provides abstraction over the specific networking methods. This makes the classes -using `NetworkPacketTransporter` 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. +using `NetworkPacketTransporter` independent of both the specific networking API and the underlying transport-layer +protocol of choice, therefore allowing 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. @@ -37,15 +42,16 @@ try { npconn = NinePConnection(NetworkPacketTransporterJavaNet("net!9p.mydomain.com!564")) } catch (uhe: UnresolvableHostException) { // failed :( + // what now? } ``` -While `NetworkPacketTransporter` 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. +While `NetworkPacketTransporter`'s implementation of choice initializes the transport-layer connection as soon as it's +instanced, this is not true for `NinePConnection` and the 9P connection it manages. The reason why this class behaves in +such way lies in its purpose, which is to only expose methods that coincide 1:1 with 9P's protocol message types. +Therefore, providing an automated way to initialize the protocol would mix two levels of abstraction in the same class. +For this purpose, the `initNineP` utility function is a shorthand that can do exactly this for you, although it's +possible to do so manually by using the 9P primitives. A word on Android ----------------- |