JTC 1.0 – documentation

Overview

Java To Cli is a plugin for java applications, that enables to reveal API, written in java for use in Bash command line (cli). This can be used by Linux users such as Linux system administrators to preform fast operations on Java applications through the environment they are used to instead of through graphic User Interface. JTC can also useful for integration between java to bash script that is good for automatic operations that can be done on the java applications. This tool can be treated like web-service of an application, the difference is that its client can use it using pure Bash script command without additional external program in some programming language.

Ease of use

JTC is created to save the developers the overhead of building the integration between Java and Bash cli. After deploying the JTC plugin in the server and client side withing short few steps, the developers can focus on building the API itself only.

Quick tutorial – how to use it

server side:

install the JTC server side as part of your Java application – see instructions below.
How to Build your API:

2.1 create a new java package as part of your source code in which the API classes will be located.

2.2 you can add API classes to a package that is dedicated for this purpose in the application.
Example: add in your application source code the package jtcapi.
Create a class called ApiExample.
2.2 add public methods in this class which will be used as API methods.

The parameters that jtc can handle are devided to 3 main groups:

simple types parameters - These params can be evaluated straight by the JTC engine.
This set contains the types: String, int, double and boolean.
Cliable parameters - bean type parameters. i.e. Parameters of object whose field can be accessed and changed using get and set method.
How to build Cliable objects - In order for object to be Cliable it should be marked as implement the Cliable interface. This is an empty interface that developers who use it means that they are responsibile for exposing the relevant properties of their object with getter and setter. For this matter no need to create new objects but instead wrap existing objects with this mechanism.
Composite parameters – composite objects that are not defined as Cliable can be also used but the use of them is limited.
Note: JTC 1.0 don't support the modification of parameters of type: array, maps, and other complex data-structure.

Naming the parmeters – since evaluation of the methods is done in runtime,
the parameter names are not part of the method signiture (at least not in Java 1.5)

JTC however enable a hook to provide the API users the parameter names, by adding the ParametNames annotation that should include the oredered list of parameter's names as they appear in the method's signiture. (see Example 1).

Example 1:
@ParameterNames("a b")

public int summarize(int a, int b){

return a+b;

}

good. Now your API classes are ready. Need just to configure few more things.

Regarding the connection from your bash clients:

create java object that will extend the JTCAbstractServlet. All you need to implement in the new object is the getPackageName() in which you will let JTC engine know the API package name. For example if your API classes exist in package com.jtc.javatocliapi , than the method should return “com.jtc.javatocliapi” .
JTC 1.0 doesn't support in authentication for users (username, password). Developers can add it if their system requires it or wait for JTC 2.0
to activate the JTC servlet add the following extensions to the web.xml file:

<servlet-name>jtc</servlet-name>

<servlet-class>Servlet class name and its path (for example com.jtc.javatocli.JTCServlet)</servlet-class>

<load-on-startup>2</load-on-startup>

</servlet>

...

<servlet-mapping>

<servlet-name>jtc</servlet-name>
<url-pattern>/jtc</url-pattern>
</servlet-mapping>

Make sure that your web-server definitions support session and that is time-out is configured to a reasonable time. (the time that your bash users will need for a session using your API.
Note in order to be able to compile the jtc sources you need to attach the external jar:

servlet-api.jar which is a public free library (of apache)and it's available in the net.

That's it!

client side:

install the JTC client side as part of your Java application – copy the file jtc a local path in the client machine. Note the directory in which jtc is installed should get writing permission
(to enable saving the session-cookie see below).
Configuration of the jtc file-
1. for changing the ip of the host name change the filed:

HOST=${HOST:-”host name”} default is localhost

for start using the jtc- in the bash command line:
1. switch
  to the directory where jtc is install.
2. Type ./jtc you will see welcoming from the jtc servlet and a few instructions

from now on type your jtc commands starting with the prefix ./jtc in the beginning of each one of them.
./jtc <the rest of the command line>

examples of using the jtc language
1. type >./jtc services
  and get the list of available API classes that are in the package that was defined in the server side (see server side 2.1).
2. type >./jtc [some class name]
  and get the list of available methods that are well defined as jtc API methods for the clients use. It is displayed as the methods signiture:

token 1 is the return value of this method, token 2 is the method's name and than pairs of parameter type and parameter name separated by comma.

In order to operate method whose required parameters types are simple, type the command:

>./jtc [class name] [method name] param1 param2 {etc}
(for example ./jtc ApiExample summarized 2 4)
note that each simple type ( String, int, double and boolean ) can be represented in jtc client side as string. Where boolean parameter that can be sent are the constants “true” or “false”

using cliable object (complex object):

Example:

say that as part of the api, the server contains the following cliable object:
public class Entity implements Cliable {

private String name;

public Entity(){

}

public String getName(){

return name;

}

public void setName(String name){

this.name = name;

}

}
note that this class may be located in any package of the application and not necessarily in the package where the API classes are located.

As part of the API classes will be added the following methods:

Class ApiExample

...

@ParameterNames("id”)

public Entity getEntity(int id){

Entity entity = DB.loadEntity(id);

validate(entity);

return entity;

}

@ParameterNames("entity”)

public void runAction(Entity entity){

some_service.run(entity);

}

now for the use of it from the command line
>./jtc ApiExample

the list of avaiable methods will be displayed:
Entity getEntity int id

void runAction Entity entity
than the command line user can get the Entity object

>./jtc ApiExample getEntity 124

and return:
Entity@7662474

This return value is a reference to this Entity object. The possibilities of actions using this reference. To learn you can simply type it again

> ./jtcEntiy@7662474

and get:

#Entity: content of fields ##

String name = marko

##possible commands for cliable object:

you can now get and set the simple type values of this cliable object using getter and setters
cliable can also contain cliable paramter whose options are recursively the same.
So possible action can be for example:
> ./jtc Entiy@7662474 set name Bob

Then if you want to varify the change press:
> ./jtc Entiy@7662474
and you'll get

#Entity: content of fields ##

String name = marko

##possible commands for cliable object:

the modified Cliable object Entity can be used as a parameter in another API method:
>./jtc ApiExample runAction Entity@7662474

The reference of the Cliable objects that is used in jtc are save in the HTTP session so the rules of session affective on them. That means:

every object that a user is using and modifying cannot be accessed or used by another user in another session. (unless it is being saved in the application itself using API method that was written for this matter).
The object will be erased after the session is deleted. i.e. Within the time that is defined in the session time-out. No possible access to those reference will be possible afterwards
for communicating with the session object, a session cookie is saved in the client side in the file cook.txt. Therefore the directory in which jtc is installed should enbale writing permission (at least in this local directory)

Good Luck