Skip to content

Commit

Permalink
doc updates
Browse files Browse the repository at this point in the history
  • Loading branch information
NaveenB2004 committed May 6, 2024
1 parent 7134f64 commit 91b8cb7
Show file tree
Hide file tree
Showing 3 changed files with 80 additions and 2 deletions.
68 changes: 68 additions & 0 deletions Docs/Dev/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# Developer guids for Socket Data Handler

My recommendation is read this after you go through the [User guids for Socket Data Handler](../User/README.md).

- [Developer guids for Socket Data Handler](#developer-guids-for-socket-data-handler)
- [Data Types](#data-types)
- [The `DataHandler`](#the-datahandler)
- [The `header`](#the-header)
- [The `timestamp`](#the-timestamp)
- [Appending the content](#appending-the-content)

## Data types

`Socket Data Handler` is using 3 data types for communications.

- NONE (just a `String` request of the `header`) [type `0`]
- FILE (`java.io.File`) [type `1`]
- OBJECT (any `serializable` object) [type `2`]

## The `DataHandler`

You must need a instance of `DataHandler` for send and receive data using this library. It's only bound to this library,
and it's **not a must** for the protocol. For more info. please look at the `Java-Doc`.

## The `header`

`Socket Data Handler` using a unique protocol for communications. If you are going to contribute or make your own
library for this, you should know how it works.

The main part of this protocol is the `header`. In the library,
the [`DataProcessor`](../../src/main/java/io/github/naveenb2004/SocketDataHandler/DataProcessor.java) is the core for
making that `header` (the `serialize` method). All `header`s are `UTF-8 String`s.

> Sample header
```json
{6,0,0}
```

`header` is only containing 3 elements enclosed by `{}` and seperated by `,`.

- The first element is the `bytes length of the request (UTF-8 String)`.
- The second element is the `data type`
- The third element is the `bytes length of the body`

Let's assume that we want to send a `File` of `2KB` with the `request`, `/samleFile`. Then the `header` is like this.

```json
{10,1,2048}
```

Now the library knows the bounds of the **variables**!

## The `timestamp`

All invocation of the `send` method is making a header (please look at [The header](#the-header) section for more about
the `header`s). The `timestamp` is part of the request content, but not showed-up in `header`. Timestamp is using
the [`Java` system milliseconds](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/System.html#currentTimeMillis()).
If you're going to use `ping` requests, please take a look at that. But why it's not in `header`? It's because
the `timestamp` always has **13 bytes**. It can be hardcoded!

## Appending the content

- Append the `header`
- Append the `request`
- Append the `timestamp`
- If it's a `File`, append the `file extension` and `$` (eg: myImage.png -> `png$`)
- If there's a body, append it
12 changes: 11 additions & 1 deletion Docs/User/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
- [Receiving pre-updates](#receiving-pre-updates)
- [Send data](#send-data)
- [Close socket](#close-socket)
- [Further Reading](#further-reading)

## Import into the project

Expand Down Expand Up @@ -134,6 +135,11 @@ try {
}
```

## Connection between `onUpdateReceived` and `preUpdateSeen`

When an update received to the `receiver`/`sender`, it automatically give a `UUID (Universally Unique Identifier)` for
that request/response. If your request/response is eligible for `pre-update` it will automatically share that `UUID`.

## Close socket

You can either direct close the socket or use `close` method of your receiver class that `extends` with
Expand All @@ -145,4 +151,8 @@ try {
} catch (IOException e) {
throw new RuntimeException(e);
}
```
```

## Further reading

Please take a look at the `Java-Doc` to get a clear idea about methods and interfaces.
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ public static void setDefaultBufferSize(int defaultBufferSize) {
@Synchronized
public void send(@NonNull DataHandler dataHandler) throws IOException {
OutputStream os = SOCKET.getOutputStream();
byte[] buffer = new byte[Math.toIntExact(defaultBufferSize)];
byte[] buffer = new byte[defaultBufferSize];
PreDataHandler preDataHandler = null;
if (dataHandler.getDataType() != DataHandler.DataType.NONE) {
preDataHandler = new PreDataHandler(PRE_UPDATE_HANDLER, dataHandler.getUUID(),
Expand Down

0 comments on commit 91b8cb7

Please sign in to comment.