JarCastingKATANA SDK for Java 8
Java SDK to interface with the KATANA™ framework (https://kusanagi.io).
Requirements
Installation
To install and use the Java SDK you'll need to first install the JDK 1.8. To do so using apt you can run the following from the command-line:
$ sudo apt-add-repository ppa:webupd8team/java
$ sudo apt-get update
$ sudo apt-get install oracle-java8-installer
The SDK can then be built with either Maven or Gradle.
If using Maven, add the following in your pom.xml file:
<dependency>
<groupId>io.kusanagi</groupId>
<artifactId>katana-sdk-java8</artifactId>
<version>2.1.0</version>
</dependency>
Or, if using Gradle, add the following in your build.gradle file:
dependencies {
compile group: 'io.kusanagi', name: 'katana-sdk-java8', version: '2.1.0'
}
Getting Started
The KATANA™ SDK is fairly simple to use. We begin by first defining the model of our components using configuration files.
Here we'll use XML, but the framework also supports both JSON and YAML formats.
First, create a file named middleware.xml, with the following configuration:
<?xml version="1.0" encoding="UTF-8"?>
<middleware xmlns="urn:katana:middleware" name="middleware_name" version="middleware_version" protocol="urn:katana:protocol:http">
...
<engine runner="urn:katana:runner:java8" path="middleware_file.jar" single-process=true>
<variable name="workers" value="5"/>
...
</middleware>
Then, create a file named service.xml, with the following configuration:
<?xml version="1.0" encoding="UTF-8"?>
<service xmlns="urn:katana:service" name="service_name" version="service_version">
...
<engine runner="urn:katana:runner:java8" path="service_file.jar" single-process=true>
<variable name="workers" value="5"/>
...
</service>
Now, create a file named middleware.class.java, and add the following source code for the Middleware, which handles both a Request and a Response:
import io.kusanagi.katana.sdk.Middleware;
import io.kusanagi.katana.sdk.Callable;
import io.kusanagi.katana.sdk.Request;
import io.kusanagi.katana.sdk.Response;
public class Middleware {
public static void main(String[] args) {
Middleware middleware = new Middleware(args);
middleware.request(request -> {
// your logic here
return request;
}
});
middleware.response(response -> {
// your logic here
return response;
}
});
middleware.run();
}
}
And also create a file named service.class.java, and add the following source code for the Service, which registers an action:
import io.kusanagi.katana.sdk.Service;
import io.kusanagi.katana.sdk.Callable;
import io.kusanagi.katana.sdk.Action;
public class Service {
public static void main(String[] args) {
Service service = new Service(args);
service.action("actionName", action -> {
// your logic here
return action;
}
});
service.run();
}
}
Examples
The following example is a Middleware which translates HTTP requests to CRUD actions based on REST conventions:
package com.katana.example;
import io.kusanagi.katana.sdk.Middleware;
import io.kusanagi.katana.sdk.Callable;
import io.kusanagi.katana.sdk.Request;
import java.util.Iterator;
import java.util.Map;
public class Rest {
public static void main(String[] args) {
Middleware middleware = new Middleware(args);
middleware.request(request -> {
// the URL format expected is "/{version}/{service}/{extra}"
String[] parts = request.getHttpRequest().getUrlPath().split("/");
// set the Service version
request.setServiceVersion(parts[1]);
// set the Service name
request.setServiceName(parts[2]);
boolean hasExtraPath = parts.length == 4 && !parts[3].isEmpty();
String method = request.getHttpRequest().getMethod();
// resolve the Service action to call
switch (method) {
case "GET":
return request.setActionName(hasExtraPath ? "read" : "list");
case "POST":
return request.setActionName("create");
case "PUT":
return request.setActionName("replace");
case "PATCH":
return request.setActionName("update");
case "DELETE":
return request.setActionName("delete");
default:
return request.setActionName(actionName);
}
}
});
middleware.run();
}
}
The following example is a Service named "users", with a "read" action which retrieves a user from a List and returns the entity according to the user_id parameter:
package com.katana.example;
import io.kusanagi.katana.sdk.Service;
import io.kusanagi.katana.sdk.Callable;
import io.kusanagi.katana.sdk.Action;
import java.util.ArrayList;
import java.util.List;
public class UserService {
public static void main(String[] args) {
Service service = new Service(args);
service.action("read", action -> {
// list of users, this would normally be a DB call
final List<User> users = new ArrayList<>();
users.add(new User(1, "James"));
users.add(new User(2, "Jeronimo"));
users.add(new User(3, "Fernando"));
users.add(new User(4, "Ricardo"));
users.add(new User(5, "Hugo"));
// read the incoming "id" parameter
int userId = (Integer) action.getParam("id").getValue();
User entity = null;
// find the user in the list
for (User user : users) {
if (user.getId() == userId) {
entity = user;
break;
}
}
if (entity == null) {
return action.error("User does not exist", 1, "404 Not Found");
}
action.setEntity(entity);
action.setLink("self", "/0.1.0/users/" + userId);
return action;
}
});
service.run();
}
}
Documentation
See the API for a technical reference of the SDK.
For help using the framework check the documentation.
Support
Please first read our contribution guidelines.
We use milestones to track upcoming releases inline with our versioning strategy, and as defined in our roadmap.
For commercial support see the solutions available or contact us for more information.
Contributing
If you'd like to know how you can help and support our Open Source efforts see the many ways to get involved.
Please also be sure to review our community guidelines.
License
Copyright 2016-2018 KUSANAGI S.L. (https://kusanagi.io). All rights reserved.
KUSANAGI, the sword logo, KATANA and the "K" logo are trademarks and/or registered trademarks of KUSANAGI S.L. All other trademarks are property of their respective owners.
Licensed under the MIT License. Redistributions of the source code included in this repository must retain the copyright notice found in each file.
