Built by Maven

Server API

Contents

Overview

This document discusses how to use the server API.

Main Entry Point

The main entry point object for the server API is the SocksServer object. To construct the SocksServer object, a Configuration object must be provided. Depending on how a Configuration object is constructed, a Settings object containing zero to many Setting objects must be provided.

The following is a simple example of constructing a SocksServer object:

package com.example;

import com.github.jh3nd3rs0n.jargyle.server.Configuration;
import com.github.jh3nd3rs0n.jargyle.server.Setting;
import com.github.jh3nd3rs0n.jargyle.server.Settings;
import com.github.jh3nd3rs0n.jargyle.server.SocksServer;

import java.io.IOException;

public class ServerApp {
    public static void main(String[] args) throws IOException {
        
        Setting<Object> setting = 
            Setting.newInstanceWithParsedValue(
                "port", "1234");
        
        Settings settings = Settings.of(setting);
        
        Configuration configuration = 
            Configuration.newUnmodifiableInstance(settings);
        
        SocksServer socksServer = new SocksServer(configuration);
        
        // ...
    }
}

The Setting Object and the Settings Object

The simplest way to create a Setting object is to use the method Setting.newInstanceWithParsedValue(String, String). The first String parameter would be the name of the setting. The second String parameter would be the value of the setting to be parsed.

Server API example:

package com.example;

import com.github.jh3nd3rs0n.jargyle.server.Configuration;
import com.github.jh3nd3rs0n.jargyle.server.Setting;
import com.github.jh3nd3rs0n.jargyle.server.Settings;
import com.github.jh3nd3rs0n.jargyle.server.SocksServer;

import java.io.IOException;

public class ServerApp {
    public static void main(String[] args) throws IOException {
        
        Setting<Object> port = 
            Setting.newInstanceWithParsedValue("port", "1234");
        
        Setting<Object> backlog = 
            Setting.newInstanceWithParsedValue(
                "backlog", "100");
        
        Setting<Object> socksServerSocketSettings = 
            Setting.newInstanceWithParsedValue(
                "socksServerSocketSettings", "SO_TIMEOUT=0");
        
        // ...
    }
}

A complete listing of the settings can be found here.

A Settings object can be created by using the method Settings.of(Setting...). The parameter is a varargs parameter of Setting objects.

Server API example:

package com.example;

import com.github.jh3nd3rs0n.jargyle.server.Configuration;
import com.github.jh3nd3rs0n.jargyle.server.Setting;
import com.github.jh3nd3rs0n.jargyle.server.Settings;
import com.github.jh3nd3rs0n.jargyle.server.SocksServer;

import java.io.IOException;

public class ServerApp {
    public static void main(String[] args) throws IOException {
        
        Setting<Object> port = Setting.newInstanceWithParsedValue(
            "port", "1234");
        
        Setting<Object> backlog = 
            Setting.newInstanceWithParsedValue(
                "backlog", "100");
        
        Setting<Object> socksServerSocketSettings = 
            Setting.newInstanceWithParsedValue(
                "socksServerSocketSettings", "SO_TIMEOUT=0");
        
        Settings settings = Settings.of(
            port, backlog, socksServerSocketSettings);
        
        // ...
    }
}

Unless stated otherwise, if there are Setting objects of the same name in a Settings object, then from those Setting objects the last Setting object is recognized by the SocksServer.

The Configuration Object

A Configuration object can be constructed by any of the following methods:

  • Configuration.newModifiableInstance(Settings): Constructs a modifiable Configuration object with the provided Settings object.
  • Configuration.newUnmodifiableInstance(Settings): Constructs an unmodifiable Configuration object with the provided Settings object. Any method that is to modify the Configuration object will throw a UnsupportedOperationException.
  • Configuration.newUpdatedInstance(ConfigurationRepository): Constructs an updated Configuration object with the provided ConfigurationRepository object. A ConfigurationRepository object provides the Configuration object from another source such as a file.

Server API example:

package com.example;

import com.github.jh3nd3rs0n.jargyle.server.Configuration;
import com.github.jh3nd3rs0n.jargyle.server.Setting;
import com.github.jh3nd3rs0n.jargyle.server.Settings;
import com.github.jh3nd3rs0n.jargyle.server.SocksServer;

import java.io.IOException;

public class ServerApp {
    public static void main(String[] args) throws IOException {
        
        Setting<Object> port = Setting.newInstanceWithParsedValue(
            "port", "1234");
        
        Setting<Object> backlog = 
            Setting.newInstanceWithParsedValue(
                "backlog", "100");
        
        Setting<Object> socksServerSocketSettings = 
            Setting.newInstanceWithParsedValue(
                "socksServerSocketSettings", "SO_TIMEOUT=0");
        
        Settings settings = Settings.of(
            port, backlog, socksServerSocketSettings);
        
        Configuration configuration =
            Configuration.newUnmodifiableInstance(settings);
        
        // ...
    }
}

The SocksServer Object

As mentioned earlier, to construct the SocksServer object, a Configuration object must be provided.

Server API example:

package com.example;

import com.github.jh3nd3rs0n.jargyle.server.Configuration;
import com.github.jh3nd3rs0n.jargyle.server.Setting;
import com.github.jh3nd3rs0n.jargyle.server.Settings;
import com.github.jh3nd3rs0n.jargyle.server.SocksServer;

import java.io.IOException;

public class ServerApp {
    public static void main(String[] args) throws IOException {
        
        Setting<Object> port = Setting.newInstanceWithParsedValue(
            "port", "1234");
        
        Setting<Object> backlog = 
            Setting.newInstanceWithParsedValue(
                "backlog", "100");
        
        Setting<Object> socksServerSocketSettings = 
            Setting.newInstanceWithParsedValue(
                "socksServerSocketSettings", "SO_TIMEOUT=0");
        
        Settings settings = Settings.of(
            port, backlog, socksServerSocketSettings);
        
        Configuration configuration =
            Configuration.newUnmodifiableInstance(settings);
        
        SocksServer socksServer = new SocksServer(configuration);
        
        // ...
    }
}

The SocksServer object has the following methods:

  • getConfiguration(): Returns the Configuration object provided to this SocksServer object
  • getHost(): Returns the Host object that this SocksServer object is bound to when the state of this SocksServer is set to STARTED. Otherwise, it returns null
  • getPort(): Returns the Port object that this SocksServer object is bound to when the state of this SocksServer is set to STARTED. Otherwise, it returns null
  • getState(): Returns the state of this SocksServer object
  • start(): Starts the SocksServer object
  • stop(): Stops the SocksServer object

Server API example:

package com.example;

import com.github.jh3nd3rs0n.jargyle.server.Configuration;
import com.github.jh3nd3rs0n.jargyle.server.Setting;
import com.github.jh3nd3rs0n.jargyle.server.Settings;
import com.github.jh3nd3rs0n.jargyle.server.SocksServer;

import java.io.IOException;

public class ServerApp {
    public static void main(String[] args) throws IOException {
        
        Setting<Object> port = Setting.newInstanceWithParsedValue(
            "port", "1234");
        
        Setting<Object> backlog = 
            Setting.newInstanceWithParsedValue(
                "backlog", "100");
        
        Setting<Object> socksServerSocketSettings = 
            Setting.newInstanceWithParsedValue(
                "socksServerSocketSettings", "SO_TIMEOUT=0");
        
        Settings settings = Settings.of(
            port, backlog, socksServerSocketSettings);
        
        Configuration configuration =
            Configuration.newUnmodifiableInstance(settings);
        
        SocksServer socksServer = new SocksServer(configuration);
        
        socksServer.start();
        
        System.out.println(
            "Listening on port " 
            + socksServer.getPort() 
            + " at " 
            + socksServer.getHost());
    }
}