An android server based on ServerSocket.
Add the dependency in build.gradle (App module)
compile 'com.eukaprotech.localserver:localserver:1.0.0@aar'
Add permission in manifest file
<uses-permission android:name="android.permission.INTERNET" />
localServer = new LocalServer(context) {
@Override
public int onInitPort() {
return 8888; //Set preferred port. Port 0 means to select an arbitrary unused port
}
@Override
public void onConfigured(String ip_address, int port) {
// ip_address (host) and port, the server is running on. You can display these values for purpose of browsing the server from a browser or a http client
}
@Override
public void onError(Exception e) {
//log errors from Exceptions thrown
}
@Override
public boolean appDebug() {
return false; //true implies the server will respond with detailed debug errors; for every 500 Internal Server Error response
}
};
localServer.start(); // also used to restart the server when stopedRemember to shut down the server:
localServer.stop();To check whether server is running:
localServer.isRunning(); localServer.route("path", HttpHandler); //first input is the path, second is a class implementing a HttpHandler interface
localServer.route("/", new HttpHandler() { // example using an anonymous class implementing HttpHandler interface
@Override
public Response onHandle(Exchange exchange) {
return ResponseHandler.string("content");
}
});The HttpHandler interface declares only one function onHandle from which you get the object of class Exchange. The object, Exchange, contains information from a client request such as:
- path (the path set on routing e.g "/home")
- URI (the complete browsable link from the above path e.g "http://192.168.0.34:8888/home")
- port (the port the server is running on e.g 8888)
- ip_address (the ip_address the server is running on e.g "192.168.0.34")
- client ip_address
- request method (GET, POST,)
- request Headers (from the client)
- parameters (from the client; both query parameters and post parameters bundled together)
- route parameters (captured segments of the URI determined by the routing syntax used)
- response Headers (to be sent to the client)
The onHandle function requires a return of an object of a class implementing Response interface. This response will be sent to the client. To build the response easily, a class ResponseHandler is used. Sample responses include:
* ResponseHandler.string("content"); // a String response. Can be a html string
* ResponseHandler.asset("file name"); //To return a file saved in android asset folder
* ResponseHandler.file(new File("")); //To return a file
* ResponseHandler.JSON(new JSONObject()); ResponseHandler.JSON(new JSONArray()); //To return JSON object or array
* ResponseHandler.redirect("path"); // to redirect to a given path with a default 302 temporary-redirect
* ResponseHandler.redirect("path", 301); //a 301 permanent-redirect
* ResponseHandler.redirect("path", new HashMap<String, Object>(){}); // a redirect with the given query parameters
* ResponseHandler.redirect("path", 301, new HashMap<String, Object>(){}); // a 301 redirect with the given query parameters
* ResponseHandler.redirectBack(); // redirect back
* ResponseHandler.redirectBack(new HashMap<String, Object>(){}); // redirect back with the given query parameters
* ResponseHandler.methodNotAllowed(new ArrayList<REQUEST_METHOD>(){}); //405 Method Not Allowed response with a list of allowed methods
* ResponseHandler.requireAuthBasic("realm"); // a 401 Access Denied response
* ResponseHandler.throw404(); // a 404 Not Found response
* null; // equivalent to ResponseHandler.throw404();To capture segments of the URI within your route:
localServer.route("/client/{client_id}", new HttpHandler() {
@Override
public Response onHandle(Exchange exchange) {
//To capture the client_id, get the route parameters from the exchange.
HashMap<String, Object> route_params = exchange.getRouteParameters();
Object client_id = route_params.get("client_id"); //OR
String client_id = String.valueOf(route_params.get("client_id"));
return ResponseHandler.string("content");
}
});To set Regular Expression Constraints on the parameter add the splitter '|' followed by the constraint:
localServer.route("/client/{client_id|[0-9]+}", new HttpHandler() { // ensures that client_id must be numeric
@Override
public Response onHandle(Exchange exchange) {
//To capture the client_id, get the route parameters from the exchange.
HashMap<String, Object> route_params = exchange.getRouteParameters();
Object client_id = route_params.get("client_id"); //OR
String client_id = String.valueOf(route_params.get("client_id"));
return ResponseHandler.string("content");
}
});You may define as many route parameters as required by your route:
localServer.route("/client/{client_id}/comments/{comment}", new HttpHandler() {
@Override
public Response onHandle(Exchange exchange) {
}
});To create a custom response for a '404 Not Found':
localServer.route404(new HttpHandler() {
@Override
public Response onHandle(Exchange exchange) {
return ResponseHandler.string("content"); // This will be the response every time you throw a 404 error response using ResponseHandler.throw404(); or when the server does not find a set routing for a request from a client.
}
});A catch-all route can be used to catch all client requests that are not routed. This intercepts the 404 not found route.
localServer.route404Intercept(new HttpHandler() {
@Override
public Response onHandle(Exchange exchange) {
//Here you can filter URIs that are crucial and return their respective response types.
//You can return a ResponseHandler.throw404(); for URIs that deserve a '404 Not Found' response.
return ResponseHandler.string("content");
}
});The basic auth value from a client can be catured from the request headers of the Exchange. To easen this process a RequestHandler class is used:
HashMap<String, String> credentials = RequestHandler.getBasicAuthCredentials(exchange);
if(credentials != null){
String username = credentials.get("username");
String password = credentials.get("password");
}Let us assume that a .png image file has been posted among the parameters by a client using the key "avatar":
HashMap<String, Object> parameters = exchange.getParameters();
Object avatar = parameters.get("avatar");
if (avatar instanceof HashMap) { // A value of type HashMap signifies a file from parameters
HashMap<String, Object> fileMap = (HashMap<String, Object>) avatar;
String filename = fileMap.get("filename").toString();
String contentType = fileMap.get("Content-Type").toString();
Object _file = fileMap.get("file");
ByteArrayOutputStream byteArrayOutputStream = (ByteArrayOutputStream) _file;
File documentsDir = Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_DOCUMENTS);
File file = new File(documentsDir, "the_avatar_image.png");
try {
FileOutputStream outF = new FileOutputStream(file);
byteArrayOutputStream.writeTo(outF);
try {
outF.close();
} catch (Exception ex) {
}
} catch (Exception ex) {}
}- Considering this is a local server, only devices under the same local network as the device hosting the server can browse the server.
- In case of conflict between a route with route-parameters and one without, the server gives priority to the route without.
- The server does not allow slashes in route parameters regardless of how you define the constraint. In case you require parameters with slashes, utilise query parameters.
- If both the server and client are on the same device, avoid letting the server overwrite the files sent by the client; definitely this will corrupt the transfer of the files.
- The server can handle multiple clients through multithreading.
- One of the applications of this server would be creating a local media server; whereby you can share/browse media files from a device. Any frequently required resources such as javascript or css files can be bundled in an android app under the assets folder and returned to clients using ResponseHandler.asset("file name");.
