doc updates

Docs/SampleProject/pom.xml

@@ -0,0 +1,76 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ Copyright 2024 Naveen Balasooriya
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License");
+  ~ you may not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~
+  ~     http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  -->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>io.github.naveenb2004</groupId>
+    <artifactId>SampleProject</artifactId>
+    <version>1.1.0</version>
+
+    <name>SampleProject</name>
+    <description>Sample codes for Socket Data Handler!</description>
+    <url>https://github.com/NaveenB2004/SocketDataHandler</url>
+    <inceptionYear>2024</inceptionYear>
+
+    <properties>
+        <java.version>11</java.version>
+        <maven.compiler.source>${java.version}</maven.compiler.source>
+        <maven.compiler.target>${java.version}</maven.compiler.target>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+        <!-- dependency versions -->
+        <ver.lombok>1.18.30</ver.lombok>
+        <ver.SocketDataHandler>1.1.0</ver.SocketDataHandler>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.projectlombok</groupId>
+            <artifactId>lombok</artifactId>
+            <version>${ver.lombok}</version>
+        </dependency>
+        <dependency>
+            <groupId>io.github.naveenb2004</groupId>
+            <artifactId>SocketDataHandler</artifactId>
+            <version>1.1.0</version>
+        </dependency>
+    </dependencies>
+
+    <licenses>
+        <license>
+            <name>The Apache License, Version 2.0</name>
+            <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
+            <distribution>repo</distribution>
+        </license>
+    </licenses>
+
+    <developers>
+        <developer>
+            <id>NaveenB2004</id>
+            <name>Naveen Balasooriya</name>
+            <email>[email protected]</email>
+            <url>https://github.com/NaveenB2004</url>
+            <timezone>UTC+05:30</timezone>
+            <properties>
+                <!-- messenger platform -->
+                <Telegram>https://t.me/NaveenB2004</Telegram>
+            </properties>
+        </developer>
+    </developers>
+</project>

src/test/java/Client/Client.java → Docs/SampleProject/src/main/java/io/github/naveenb2004/SampleProject/Client/Client.java

@@ -14,13 +14,13 @@
  * limitations under the License.
  */
 
-package Client;
+package io.github.naveenb2004.SampleProject.Client;
 
 import java.io.IOException;
 import java.net.Socket;
 
 public class Client {
-    public void connect(int port) {
+    public static void connect(int port) {
         try {
             // connect to the server
             Socket socket = new Socket("localhost", port);

src/test/java/Client/ClientHelper.java → Docs/SampleProject/src/main/java/io/github/naveenb2004/SampleProject/Client/ClientHelper.java

@@ -14,9 +14,9 @@
  * limitations under the License.
  */
 
-package Client;
+package io.github.naveenb2004.SampleProject.Client;
 
-import Common.SampleObject;
+import io.github.naveenb2004.SampleProject.Common.SampleObject;
 import io.github.naveenb2004.SocketDataHandler.DataHandler;
 import io.github.naveenb2004.SocketDataHandler.DataProcessor;
 import io.github.naveenb2004.SocketDataHandler.SocketDataHandler;
@@ -67,7 +67,8 @@ protected void sendText() {
     // send sample file
     protected void sendFile() {
         System.out.println("Client : Sending File...");
-        File file = new File("src/test/java/Common/SampleFile.jpg");
+        File file = new File(
+                "Docs/SampleProject/src/main/java/io/github/naveenb2004/SampleProject/Common/SampleFile.jpg");
         DataHandler dataHandler = new DataHandler("/SendFile", file);
 
         try {

src/test/java/Common/SampleObject.java → Docs/SampleProject/src/main/java/io/github/naveenb2004/SampleProject/Common/SampleObject.java

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package Common;
+package io.github.naveenb2004.SampleProject.Common;
 
 import lombok.Builder;
 import lombok.Getter;

src/test/java/Main.java → Docs/SampleProject/src/main/java/io/github/naveenb2004/SampleProject/Main.java

@@ -14,6 +14,24 @@
  * limitations under the License.
  */
 
+package io.github.naveenb2004.SampleProject;/*
+ * Copyright 2024 Naveen Balasooriya
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import io.github.naveenb2004.SampleProject.Client.Client;
+import io.github.naveenb2004.SampleProject.Server.Server;
 import io.github.naveenb2004.SocketDataHandler.SocketDataHandler;
 import lombok.SneakyThrows;
 
@@ -30,9 +48,9 @@ public static void main(String[] args) {
         // set default temporary folder for files downloading
         SocketDataHandler.setTempFolder(new File("Temp"));
 
-        new Server.Server().connect(port);
+        Server.connect(port);
         Thread.sleep(3000);
-        new Client.Client().connect(port);
+        Client.connect(port);
     }
 
 }

src/test/java/Server/Server.java → Docs/SampleProject/src/main/java/io/github/naveenb2004/SampleProject/Server/Server.java

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package Server;
+package io.github.naveenb2004.SampleProject.Server;
 
 import lombok.Cleanup;
 
@@ -23,7 +23,7 @@
 import java.net.Socket;
 
 public class Server {
-    public void connect(int port) {
+    public static void connect(int port) {
         new Thread(() -> {
             try {
                 // create new server socket

src/test/java/Server/ServerHelper.java → Docs/SampleProject/src/main/java/io/github/naveenb2004/SampleProject/Server/ServerHelper.java

@@ -14,9 +14,9 @@
  * limitations under the License.
  */
 
-package Server;
+package io.github.naveenb2004.SampleProject.Server;
 
-import Common.SampleObject;
+import io.github.naveenb2004.SampleProject.Common.SampleObject;
 import io.github.naveenb2004.SocketDataHandler.DataHandler;
 import io.github.naveenb2004.SocketDataHandler.DataProcessor;
 import io.github.naveenb2004.SocketDataHandler.PreUpdateHandler.PreDataHandler;

Docs/User/README.md

@@ -0,0 +1,148 @@
+# User guids for Socket Data Handler
+
+- [User guids for Socket Data Handler](#user-guids-for-socket-data-handler)
+    - [Import into the project](#import-into-the-project)
+    - [Common library settings](#common-library-settings)
+    - [Setting up the receiver](#setting-up-the-receiver)
+    - [Connect socket and library](#connect-socket-and-library)
+    - [Receiving pre-updates](#receiving-pre-updates)
+    - [Send data](#send-data)
+    - [Close socket](#close-socket)
+
+## Import into the project
+
+[![Central Repository](https://img.shields.io/maven-central/v/io.github.naveenb2004/SocketDataHandler
+)](https://central.sonatype.com/artifact/io.github.naveenb2004/SocketDataHandler)
+[![Minimum JDK version](https://img.shields.io/badge/Minumum_JDK-v11-green)](#)\
+If you are using project managers like `Maven`, `Gradle` etc., please take a look at
+the [Central repository page for this project](https://central.sonatype.com/artifact/io.github.naveenb2004/SocketDataHandler).
+You can find most of the import snippets for project managers from there. For `Maven`:
+
+```xml
+
+<dependency>
+    <groupId>io.github.naveenb2004</groupId>
+    <artifactId>SocketDataHandler</artifactId>
+    <version><!-- set version --></version>
+</dependency>
+```
+
+## Common library settings
+
+In this library, you can set up maximum IO buffer size for data chunks (in `bytes`) and default location for work
+with `Files`. To do that place this code before any initialization of the `SocketDataHandler`.
+
+```java
+// set default maximum buffer size for chunks
+SocketDataHandler.setDefaultBufferSize(1024);
+
+// set default temporary folder for files downloading
+SocketDataHandler.setTempFolder(new File("Temp"));
+```
+
+## Setting up the receiver
+
+Now you're good to code your receiver file. To do that, make a class that `extends` the `SocketDataHandler` and
+implement the required constructors and methods in that class.
+
+> MySocket.java
+
+```java
+public class MySocket extends SocketDataHandler {
+    public MySocket(Socket SOCKET) {
+        super(SOCKET);
+    }
+
+    @Override
+    public void onUpdateReceived(DataHandler update) {
+
+    }
+
+    @Override
+    public void onDisconnected(DataProcessor.DisconnectStatus status, Exception exception) {
+
+    }
+}
+```
+
+All completed updates are pushed to the `onUpdateReceived(DataHandler update)` method and if socket disconnected (either
+end) it will push to `onDisconnected(DataProcessor.DisconnectStatus status, Exception exception)` method.
+
+## Connect socket and library
+
+`SocketDataHandler` is just a library to manage socket IO operations. So you need to work on your network operations.
+
+```java
+// connect to the server
+Socket socket = new Socket("localhost", port);
+
+// connect socket with library
+MySocket clientSocket = new MySocket(socket);
+```
+
+## Receiving pre-updates
+
+`Pre-update` means that uncompleted, processing (receiving or sending) update. You can only get pre-updates
+for `Serializable Objects` and `Files`. To do that you need to implement a `pre-updates watcher` class and register it
+with the `receiver` class that `extends` the `SocketDataHandler`.
+
+> MyPreUpdateWatcher.java
+
+```java
+public class MyPreUpdateReceiver implements PreUpdateWatcher {
+    @Override
+    public void onPreUpdateSeen(PreDataHandler preUpdate) {
+
+    }
+}
+```
+
+> MySocket.java
+
+```java
+public class MySocket extends SocketDataHandler {
+    public MySocket(Socket SOCKET) {
+        super(SOCKET);
+        // register the watcher
+        PreUpdateHandler watcher = getPRE_UPDATE_HANDLER();
+        watcher.addWatcher(new MyPreUpdateReceiver());
+    }
+
+    @Override
+    public void onUpdateReceived(DataHandler update) {
+
+    }
+
+    @Override
+    public void onDisconnected(DataProcessor.DisconnectStatus status, Exception exception) {
+
+    }
+}
+```
+
+## Send data
+
+You can use `DataHandler` object to store your request and use `send` method to send it. Note that the `send` method is
+part of your receiver class that `extends` with the `SocketDataHandler`.
+
+```java
+DataHandler dataHandler = new DataHandler("/SendText");
+try {
+    clientSocket.send(dataHandler);
+} catch (IOException e) {
+    throw new RuntimeException(e);
+}
+```
+
+## Close socket
+
+You can either direct close the socket or use `close` method of your receiver class that `extends` with
+the `SocketDataHandler`. On successful close, you will receive an update for `onDisconneted`.
+
+```java
+try {
+    clientSocket.close();
+} catch (IOException e) {
+    throw new RuntimeException(e);
+}
+```

README.md

@@ -44,7 +44,7 @@ You can find most of the import snippets for project managers from there. For `M
 ## Usage
 
 - Please refer to the [user guids](Docs/User/README.md) to know how this library is going to make your work easy 😎. If
-  you feel too lazy to read docs (not recommended), here are [some example codes](src/test/java) for you!
+  you feel too lazy to read docs (not recommended), here are [some example codes](Docs/SampleProject) for you!
 - Please refer to the [developer guids](Docs/Dev/README.md) to know how developers are going to smile (or maybe laugh at
   me) 😁.