Using Remote Services

1. Publishing Services
2. Browsing Services
3. Connecting to Remote Services
4. Calling Remote Services
5. Accessing Services Via HTTP
6. Advanced Service Provision Topics

As far as security is concerned, there is only one security model to maintain. The same users who may access web pages are the same users who may access services used for those pages and for remote service access in general. The security is integrated into the services via the security annotations, as shown in the security tutorial. Proper security definition within the services and assignment to the users is critical. It really sucks to have a web crawler or malicious user delete precious content, so ensure methods are locked down and permissions are assigned correctly. In practice, the security within the Service API is locked down by default, but that is of no protection if security is not applied correctly.

Once the service is ready to go, and packaged in a jar (via ant jar), and that jar is on the classpath, it will automatically be discovered and be available for page construction, javascript, and local and remote access.

Clicking on a service shows the methods available from that service:

The getLog() method, for example, returns a LogBundle and requires the org.benow.log.LogService.invoke permission.

The service listing provides an easy way to determine which services are available. The easy discovery of services and methods can be a help when constructing applications with much functionality and eases multi-user/distributed development. It also provides a nice way for users to access site functionality without having to go through pages, which makes make for interesting remote application and remote site integration possibilities.

First, we'll want to connect to the service. We can do that using the HttpRemoteServices accessor class. Open src/java/test/org/benow/web/Tutorial.java and find the doConnect() method.

RemoteServices rsvcs=new HttpRemoteServices(user, pass, host, port);
List<ServiceSpecification> svcl = rsvcs.listServices();

Behind the scenes there is quite a bit being done. The request is formulated as a HTTP request with basic authentication, method and parameters (if any). The response comes back as XML which is parsed into java objects. HttpRemoteServices automates all this, so it's as simple as a local method call.

To run this example, do bin/tutorial_web.sh connect or bin\tutorial_web.bat connect in windows. To specify different connect param, add a user, pass, host and port, in that order, ie bin/tutorial_web.sh connect fred fredspass fred.com 80.

RemoteServices rsvcs=new HttpRemoteServices(user, pass, host, port);
TutorialService svc=(TutorialService) rsvcs.takeService(TutorialService.class);
try {
  System.out.println("All people:");
  List<Person> people=svc.getPeople();
  for (Person p: people)
    System.out.println("\t"+p);
  
  System.out.println("People in Heresville:");
  people=svc.getPeopleInCity("Heresville");
  for (Person p: people)
    System.out.println("\t"+p);
  
  System.out.println("People in 180cm or over:");
  people=svc.getPeopleOfHeight(180);
  for (Person p: people)
    System.out.println("\t"+p);
} finally {
  LocalServices.returnAService(svc);
}

Remote service invocation is really only useful to remote users (as opposed to running locally as in this example). The service interface and other classes used in the service must be known to the accessor... ie they must have TutorialService and Person in their classpath, but the service implementations need not be (ie no need for TutorialServiceImpl). The underlying service implementation returned by takeService(Class) is a dynamically compiled class which does the result translation. The implementation takes care of using the service accessor to make remote HTTP requests, translates results to java objects and returns them. The remote service api generates the implementation of the requested class. As dynamic compilation is done, the client must be accessing with the JDK (as opposed to the JRE) as the JDK has javac, the java compiler. It automatically finds javac for the JDK that is being used, and will burp if it can't find javac. Again, the remote service api does all the encoding, transmission, reception and decoding for you, making remote service use from java quite simple.

String serviceClassName="test.org.benow.service.TutorialSecureService";
String methodSig="deletePerson(String,String)";
String firstName="John";
String lastName="Smith";

NVPair[] params = new NVPair[] {
    new NVPair("exec", methodSig),
    new NVPair("firstName", firstName),
    new NVPair("lastName", lastName)
};

HTTPConnection conn = new HTTPConnection(host,port);
conn.addBasicAuthorization("", user, pass);

NVPair[] headers = new NVPair[2];
headers[1] = new NVPair("User-Agent", Tutorial.class.getName());

HTTPResponse response = conn.Post("/svc/"+serviceClassName, params, headers);
BufferedReader in = new BufferedReader(new InputStreamReader(response.getInputStream()));
System.out.println("Got response:");
String read = in.readLine();
while (read != null) {
  System.out.println(read);
  read = in.readLine();
}

To run this example, do bin/tutorial_web.sh http or bin\tutorial_web.bat http in windows specify connect parameters as required.

By using HTTP post directly, service requests can be made from any network aware environment. This opens your web application to advanced cross-platform usage, while keeping it secure.