Command line tools

version 7.1
feedback: 2step@zentense.com

There are some tools that can be invoked from command line. For doing this you need to invoke the JAR file 2step.jar this way:

java -jar 2step.jar

Without arguments it will print the usage and will exit. In this document we will see the different tools that can be accessed this way.

1. compile
2. compilemodel
3. geoip
4. get
5. loadtest
6. log
7. md5
8. war

1. compile

Figure 1: Files involved in 2step compilation This compile a 2step application from command line. You can also compile a 2step application from administration, where you also have the option of using an external Java compiler as jikes (by default, the javac compiler shipped with Java SDK is used). But the best way for compiling a 2step applications is using the 2step development plugin for Eclipse.

Usually 2step will detect Java compiler, but you can override default detection defining the system property JAVA_HOME as in the next example:

java -DJAVA_HOME=/usr/local/java -jar 2step.jar compile

You can also put the file tools.jar in the environment variable CLASSPATH:

export CLASSPATH=/usr/local/java/lib/tools.jar
java -jar 2step.jar compile

Without arguments, the application in the current directory will be compiled (if the current program working directory has not any 2step application, then compilation will obviously fail).

Compilation of a 2step application is complex because it involves many files, as you can see in figure 1. In the figure white files are files written by developer (Java and 2step sources, model definition if any and I18N texts if any), and the rest of files are subproducts of compilation automatically generated by Java compiler, 2step compiler, or 2step runtime during application execution.

Fortunately all of this process is done automatically by 2step compiler and is transparent to developer. A 2step application compilation is divided in four stages:

First, if a model is available for this application it is translated into a Java file (java/ModelInit.java)

Then all the Java source files under the subdirectory java are compiled and left in the subdirectory classes. There reside all the classes crated expressly for this 2step application, but you can package them as a JAR files if you wish. The advantage of having classes here is that they are automatically recompiled by 2step.

In the second step, the 2step source files (extension .2s) are compiled (being strict, are not actually compiled but translated into Java) and left in the directory step2

In the third step, the 2step source files translated into Java, are compiled and left in the directory classes which is the executable form of a 2step application.

If you want to compile a 2step application that resides in a directory other than the current working one, then you may pass the application directory as the next argument when invoking the compilation:

java -jar 2step.jar compile /path/to/application

And finally, if you have specified the application directory, then you can put extra directories or JAR files to be passed to the compiler as the last argument.

2. compilemodel

This compiles a model file and generates corresponding ModelInit.java. It usually is done automatically by 2step compiler. By default tries to compile the default model for the application in the current working directory, but a different file may be specified as an argument.

3. geoip

GeoIP is a database that maps IPs to different locations. 2step is integrated with the GeoIP countries file, which is free, and can be obtained from Maxmind. The file is usually named GeoIP.dat. It is not shipped with 2step release, because the IP countries database is not static and changes over time, so it is recommended that you get the last version directly from Maxmind.

2step uses the GeoIP database (if available) for knowing which country each IP that is served comes from, and generate accurate countries statistics for each web application.

You can use the command line simply for accessing directly GeoIP database. You can do that invoking 2step command line tools with geoip argument, the path to the GeoIP.dat file as the next argument, and the IP to be resolved as the last argument:

java -jar 2step.jar /path/to/GeoIP.dat 62.57.145.236

4. get

This command allows to execute a template or action of an application directly from command line, without any server involved in the process. The output is dumped directly to the standard output. This is useful for creating and executing 2step applications without web interface. For instance, this document you are reading, was generated this way, with an small 2step application that uses some templates to generate automatically some parts of the document.

Without arguments, it tries to load a 2step application stored in the current working directory, and, if successful, tries to execute the main action. The request parameters can optionally be specified as an argument (the last one), and, finally, the application directory may be specified if it is not the current working one.

The next sample tries to execute a foo template, with a parameter, from an application located in the /path/to/application directory:

java -jar 2step.jar get /path/to/application tplt=foo¶m1=yes

5. loadtest

This command allows to perform a load test on a 2step application. For that, it needs an argument that is the name of a properties file that describes how the load test will be performed. The properties in the file are:

allatonce: If this property exists, then property time is not taken into account and all clients begins at the same time.
baseurl: This is the base URL to be prepended to all the pagen properties. It must include the http:// and this property is mandatory.
clients: Number of clients that will be accessing concurrently to the server. Default is 5.
login: These are the parameters of the login page, if any. They will be appended to the baseurl property in order to form a complete URL. It must call the template or action with the login and password needed to login into the application.
pages: Number of pages to be requested for each client. Default is 3.
pagen: Parameters of a single request. These parameters are appended to the baseurl property to form a complete URL. There can be several of this arguments, where n is an integer beginning with 1. Each client will take one of the n available pages randomly, so the pages must not be interdependent.
rand: This is the maximum time, in hundredths of a second, that a client will randomly wait from request to request. By default is 2. This is used for making the behaviour of the load test less linear and predictable, ressembling more to the characteristics of a real environment.
sessionparam: This describes how the servlet engine encodes the session in the URL. The load test program is not able to use cookies, so it encodes the session in the URL. By default it takes the value ;jsessionid=<$sid$>, where <$sid$> is substituted by the actual session identifier of a session. This default value works well with Tomcat and the internal 2step server.
time: This is the time, in milliseconds, between clients arrivals. By default it is 120 milliseconds. Therefore, if there are 3 clients, and time between arrivals is 1000 (a second), the first client will start at moment 0, the second one second later, and the last one two seconds after the first client. The property allatonce may override this one.
timesession: This is the time, in seconds, that a client session lasts. By default is 30 seconds. For instance, if a client has to request 10 pages, and the time of the session is 30, it will request one approximately every 3 seconds.

6. log

This tool analyzes log files (whose name is passed as last argument), generates the corresponding 2step.year.stats if they did not exist, and present some statistics to output stream. The stats file is the file where all the statistics that can be seen from administration area are stored. Each year a new stats file is generated.

The main use of this command is for regenerating a stats file. For doing so, just delete the stats file and issue this command with the name of the today's log file to regenerate the stats file.

7. md5

It takes one argument which is the word to be cyphered with the MD5 algorithm that is used for cyphering passwords if Encrypt passwords is checked on general setup.

8. war

This commands generates a WAR file (Web Application Archive) that is a standard for installing web applications in servlets engine. WARs are not needed for installing a 2step application in the built-in servlet engine, but are needed for other ones, as Tomcat. For generating a WAR file just issue this command and a WAR file will be generated for the 2step application in the current working directory.

If the application resides in another directory different than the current one, just pass the application directory as an argument. There is an optional second argument which is the 2step home directory. This second argument is intended only when you want to generate WAR files for a remote server where 2step home directory is different from the one at the local machine.

Generated on Tue 14 16:01:12 CEST
	2step 7.1.46 © 2008 Zentense S.L.