jj1 webservice step by step
we will create a little json-rpc webservice in java using jj1. it’s a step by step tutorial using a fresh install of tomcat and java. if you use an ide it should be easy to adabt it. the webservice will generate an ascii banner from a string. the code to generate the ascii banner exists already and just needs to be made accessible as a webservice.
what you need
you need a default tomcat installation and a jvm (java virtula machine). to test if a jvm is available just type java at the command prompt. if something likejava version "1.6.0_07"
Java(TM) SE Runtime Environment (build 1.6.0_07-b06)
Java HotSpot(TM) Server VM (build 10.0-b23, mixed mode)
apears you have one installed. otherwise download one from sun or use your package manager to install one.
the easiest way to install tomcat is with your package manager if you use a linux like os. if there is no tomcat support take a look at the tomcat setup page.
directories
i usually create a main folder named after the project. in this folder there is a src folder for the java source, a bin folder for the compiled files and a dist folders for jars and wars. if it’s a webapp there is also a web folder which is the webapp. so for our little example app it looks like:asciiText
asciiText/src
asciiText/bin
asciiText/dist
asciiText/web
asciiText/web/WEB-INF
asciiText/web/WEB-INF/lib
dependencies
we need three jars. at first the jj1 jar. the next jar is the stringtree jar. this is used to encode/ decode json. as next we need the service implementation. save all the jars in the asciiText/web/WEB-INF/lib folder.create the context object
to access a method via json-rpc we have to expose this method to the web. in jj1 this is done via a context object. this is our first… and only java class. we will create it in a ch/kerbtier/asciitext subfolder of the src folder. the ch/kerbtier/asciiws folders represent the namespace or package where the class lives in. the file should be named AsciiContext and look like:package ch.kerbtier.asciiws;
import ch.kerbtier.asciitext.AsciiRenderer;
import com.googlecode.jj1.server.JsonRpc;
public class AsciiContext{
private AsciiRenderer renderer = new AsciiRenderer();
@JsonRpc
public String getText(String input, String font, int size){
return renderer.createAscii(input, font, size);
}
}
thats it. we publish the method getText (with the JsonRpc annotation) as a webservice. internally it just calls the createAscii method of the renderer.
web.xml
a webapplication is configured by a web.xml file which lives in the WEB-INF folder of a webapp. we need the following file:<?xml version="1.0" encoding="UTF-8"?>
<web-app>
<servlet>
<servlet-name>AsciiText</servlet-name>
<servlet-class>com.googlecode.jj1.server.Jj1Servlet</servlet-class>
<init-param>
<param-name>services</param-name>
<param-value>root=ch.kerbtier.asciiws.AsciiContext</param-value>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>AsciiText</servlet-name>
<url-pattern>/ascii</url-pattern>
</servlet-mapping>
</web-app>
this instantiates a Jj1Servlet and loads an AsciiContext instance as a jj1 context and publishes its methods directly under the url ascii.
build the whole stuff
go to your asciiText directory and type:javac -d bin -classpath web/WEB-INF/lib/asciiGenerator.jar:\
web/WEB-INF/lib/jj1.0.1.jar src/ch/kerbtier/asciiws/AsciiContext.java
this compiles the AsciiContext file and places it into your bin directory into the proper package. with the -classpath option you specify the jar files with the classes inside AsciiContext depends on. on windows you need a ; as delimiter between classpath entries.
jar cf dist/asciiws.jar -C bin ch
this creates a jar file out of the class… it’s useful if you have lots of classes, with one it’s just habit.
cp dist/asciiws.jar web/WEB-INF/lib/
copies the generated jar file into the lib folder of the webapp.
jar cf dist/asciiws.war -C web WEB-INF
this creates the file asciiws.war. now we just need to deploy it with tomcat. one easy way is to just copy it into the webapps folder. after that the webservice should be accessible trough the url http://localhost:8080/asciiws/ascii