Administration area

 version 7.1
feedback: 2step@zentense.com


Each 2step application has its own administration area. From it, you can see statistics, logs, compile the application, deploy a new version, manage access control to resources, change application setup, and more. This document will describe all of this options.

In this document this area's options will be described.


1. Accessing administration area
2. State
2.1. Status
2.1.1. System properties
2.1.2. Load averages
2.2. Activity
2.3. Statistics
3. Tools
3.1. Compile application
3.2. Update application
3.2.1. Reload application
3.2.2. Init database
3.3. SQL Console
3.4. View logs
3.4.1. Clear logs
3.5. Documentation
4. Setup
4.1. General
4.1.1. General
4.1.2. Access control
4.1.3. Java compiler
4.1.4. Database
4.1.5. Internationalization
4.2. Access control
4.2.1. Users
4.2.2. Groups
4.2.3. Modules
4.2.4. Allow / Deny rules
4.2.4.1. Method invocation rules
4.2.5. Rule precedence
4.3. Constants
5. Log out



   1. Accessing administration area

  Administration area is accessed through the subdirectory 2step of application's webspace. For instance, for entering into tutorial's administration area we would open a browser and would go to http://localhost:8080/tutorial/2step

Administration area has two modes of execution: development and production. Development server is an scenarion where changes occur continually, application is compiled lots of times, tests are done, errors happen, and speed is not important because this is an internal server only accessed by developers. On the other hand there is the production server, where application must be reliable, robust, very fast and efficient because it will be accessed by all users at the same time, and updates are rare. By default it is executed in development mode, and in general setup it can be changed to production. These are differences between the two modes:

  • Authentication: In development mode administration area is accessed freely, without authentication, while in production mode login and password will be required to access adinistration (by default 2stepadmin/admin).
  • Error presentation: In development mode stack traces are dumped in the response, as well as in log files so errors are easily detected, while in production mode exceptions are just logged but stack traces are not shown. In some applications this can generate large log files
  • Runtime inspector: In development mode, some errors launch the inspector window where you can browse runtime objects and its fields too see the runtime state when error ocurred. Runtime window can be very memory eager because runtime can have thousands of objects.
  • Compile: In development mode you can compile application from administration are
  • Deployment: In development mode you can create application deployment package that can be used to deploy application to other servers remotely.
  • Auto reload: In development mode applicaton is automatically reloaded when the application has been recompiled. This is useful when compiling application from Eclipse.



   2. State

  This group of menu items shows you different aspects of the state of 2step, as the logs, and mainly, statistics.


2.1. Status

This is the first page you see in development mode (in production mode your first page is always login). It shows you some useful information about your application.

You can see server current time, log level (normal, verbose or very verbose), at which time this application was started, number of request served, wrong requests (are the ones with wrong parameters that does not reference any application's action or template), dropped requests (the ones that are not answered due to server overload), sessions received, number of actions and templates (metrics) of this application, load averages (amount of time rendering pages and amount of time a request has been waiting for a database connection), database connection timeouts (if your application is generating timeouts then the system is heavily loaded or the executed application is doing something nasty with database connections), and a approximated calculated performance (it is not very accurated, and the first requests are always slower untill the Java virtual machine has 'warmed out' and performs at its full capacity).

At the bottom of the page there are three small pie charts. The first one (left) shows you the number of active sessions (different users browsing your page) against the maximum number of active sessions, the one at the middle shows you how many request have been served concurrently (at the same time) versus the size of database connections pool (which is the maximum concurrency allowed for this application), and the last one (right), shows you the amount of heap memory used versus the total heap size (as Java 'garbages collect' heap memory automatically this is not very useful). You can change the Java maximum heap size specifying the -Xmx parameter when invoking Java virtual machine that runs Tomcat and 2step.

If you don't see the three pie charts graphs at the bottom of this page, then it means that the jCharts library (it is distributed in the 2step package or you can get it directly from Sourceforge) is not properly installed. Copy jCharts.jar file to the $TOMCAT_HOME/shared/libs directory.

2.1.1. System properties

This page shows the complete list of Java system properties.

2.1.2. Load averages

This page shows you the load averages. Load averages are calculated through the database connection pool usage, so, if 2step is not connected to a database, no load averages will be shown. This method does not give exact values, specially under heavy loads, but you will get an idea of how much this web application is occuping your CPU. The performance shown in the status page is based on these load averages.

Load averages are calculated this way: each time a request is received, a connection from the database pool is assigned to the request, and when the response is fully rendered, the connection is freed and is ready for being assigned to another request. The time elapsed between these two events (assign and free connection) is taken as the time needed to render the page. This is true if the CPU is only rendering this page and there are not other processes spending the CPU time. If there are a lot of requests being rendered concurrently, the load averages calculated this way will give distorted results, but at least, you will see that if the server is too heavily loaded (that is the main purpose of this screen).

The graph shows the load averages for the last minute, 5 minutes and 15 minutes. Suppose that server receives a request that takes 1 second to be rendered. And one of this request is received each second for a minute. Then the graph will show the 1 minute load average raising up to 100%. Notice that the load averages can be higher than 100% (more than one request being executed concurrently).

But, what happens if we receive 10 of these requests per second? (remember that each one takes an entire second in this example... in the real world, depending on the complexity of the page and the power of your server, a request can take from 1 hundredth of a second to several seconds). Suppose that we have a pool of 10 database connections (so that we can serve up to 10 requests simultaneously). The first ten requests will be assigned to the 10 database connections. But there will not be any available connection to the eleventh request. Then the eleventh requests will be blocked until any requests frees its connection. The requests blocked time is shown as a red area in the graph. When requests are blocked it means that your server is overloaded.

And finally, when there are too much requests blocked (in this release, just 10 of them), the subsequent requests are dropped away (a 503 response code is sent to the browser that originated the requests, informing that the server is temporarily overloaded).


2.2. Activity

This pages shows you an axis chart showing pages, sessions and unique IPs that have visited our application on a daily basis. The first time you look at it you will see an empty graph, and this page is not really useful during development of your application.

But when the application is put in production, then this page gives you a lot of information. Below the image there is the table of values shown in the graph. You can click on the days and you will see two detailed (probably empty if you are just trying it) bar charts of that day showing the length of received sessions in time (right) and number of pages visited (left).

The arrows in the top of the page let you see the same graphs for the previous and the next day respectively. These arrows are in all the statistics pages and let you move through time.

Now, return to the first page with the axis chart. In the top, between the aforementioned arrows, there is the time basis selector (hourly, daily, weekly or monthly) for the graphs. Hourly, Daily and Weekly are exactly identical, but you have more monthly information (see next point).

All the information needed for generating these graphs is gathered from log files.


2.3. Statistics

You should have been seeing the same bar charts as when you clicked on a day, but now you have a graph selector (sessions, agents, languages, domains and pages). Sessions are two bar charts telling you about the length of the sessions. The rest of the graphs are pie charts. Agents let you see which browsers (Explorer, Mozilla, Opera, etc) are visiting this applications and which operating systems (Linux, Windows, MacOS...) are running, languages tells you which lenguages are selected by the browsers (this only have sense if you are running a multi-language application), countries (if GeoIP is enabled) of the host addresses that are visiting us, and finally pages wich shows which templates and actions are the most visited.

You can also reach this pages if you go to the previos menu item, select monthly graph, and click on a month. As in the previous point, all the information is gathered from log files.



   3. Tools

  In this menu group, there are some general tools for setting up the application, access to database, manage application access control and manage application constant.


3.1. Compile application

2step source applications are composed by one or more 2step scripts, lots of template files, and none or more Java files. By default, the Java files of a 2step application are inside the beanz directory or one of its subdirectories, and belong to a package whose first component is the name of the application. For instance, if the application tutorial has a beanz/Test.java source file, the full name of this class is tutorial.beanz.Test.

You can put Java sources in other places, but then they will not be recompiled automatically each time you compile the 2step application, unless you do some tuning in the java compiler setup options.

When the application is compiled and the Java files in beanz directory are compiled, then 2step code is combined with template files and the result is translated into Java.Finally this Java is also compiled.

Clicking on this link, applications begins to be compiled automatically, and the browser becomes like a terminal where you see the standard outputs. Notice that this option is only available in development mode.


3.2. Update application

Here is presented the 2step deployment utility. It compiles an application without debug information and generates a package that can be uploaded on the same screen of any other 2step instance, and the application is automatically updated and deployed on the fly.

When you create the deployment file, you can add manually in the text area some extra files that will be added to the package. Click on the button, and a file with the same name as the application and the extension 2ar can be found in the application directory. Notice that creating the deployment file is only available in development mode.

When deploying the application, select in the browser the previously generated deployment file, and upload it. The server will update and reload the application automatically. Optionally, if you included a new version of the 2step.jar in the package, checking the Reload 2step core classes checkbox will update the running version of 2step on the fly.

3.2.1. Reload application

This reloads the application. When you restart Tomcat (for example, for reloading the application), all the active sessions are lost (for instance, all shopping carts of e-commerce would be lost). If you reload the application from this point, if application-specific Java classes don't use inner classes, then active sessions will continue working after the reload.

3.2.2. Init database

Closes and reopens connections to database. Useful if you want to change the application database on the fly.


3.3. SQL Console

Here you can type SQL sentences in the text area, and see the results in a table. You can execute here any command supported by your database. You can also use the select, from, where and order by fields for constructing easily select statements that will appear in the text area.

When the checkbox Allow editing sql text area is enabled, the SQL statement is taken from the text area, and all the other form fields are ignored.


3.4. View logs

Shows you the colored output of the log file. Log files are stored in the logs subdirectory of the application directory. They are named as the application plus the ".log" extension.

Each day, at 00:00 hours, logs are rotated. For instance, if today was 30st of May of 2004, the tutorial log file would be called tutorial.log, and after changing day, it would be renamed as tutorial.log.040530 and tutorial.log would contain logs for 31st. At this time logs are also processed and saved in the 2step.stats.2004 file in the logs directory. The stats file is the one that is used to generate all the charts of points 2.2 and 2.3, and obviusly, the last part of the name is the year of the statistics.

By default, if the log file is very long, only the last 50 Kbytes are shown, though you can change this in the controls at the upper-right corner of the screen.

If you change log level in setup to verbose or very verbose, you change the information dumped in the log file. With normal log level (default) only the session information (blue), actions and templates hits (black), and errors (red), are dumped to the log. With verbose log level you also see the SQL queries executed (blue) and SQL prepared statements (purple) and variable assignations (green). With very verbose log level, tags executed (yellow) are also reported to logs.

3.4.1. Clear logs

Clears the log files. In a production environment, doing this will affect statistics quality.


3.5. Documentation

This menu item is only visible if 2step is in development mode. When clicked, it shows a page with links to all the 2step documentation available, from this document, to language reference, or Javadoc API.



   4. Setup

  Finally, in the last menu group, there are some useful actions as reloading, clearing logs or compiling application.


4.1. General

Here you can set up some general application parameters. Let's see in detail each one of the parameters, that are subdivided in the next blocks:

4.1.1. General

  • Administration mode: Development or Production. Sets the administration mode. In development mode, (default) no authentication is required for accessing administration area, and error stack traces are dumped to the output.

  • Log level: Normal, Verbose, or Very Verbose, in order of locuacity. See point 2.4 for more details. In normal mode, errors are reported in the log without stack trace. Take into account that in verbose and very verbose modes, you need to recompile application to see all the log messages dumped.

  • GeoIP countries file: GeoIP is a geographical IP database: given an IP it tells you at which country this IP is located. 2step, if present, uses it for guessing which country a new session comes from. For enabling GeoIP. download freely the last GeoIP countries database from Maxmind and put in this field where the file is located.

  • Session timeout: Sets the idle session timeout (in seconds). This setting will override the default servlet container session timeout setting. Notice that you can change the idle session timeout directly in the container.

  • XSL root: Path (relative to web application directory) where XSL files can be found for XSLT requests. Suppose an application with a template called xml that can be invoked with http://localhost:8080/webapp?tplt=xml. If this template have a contentype of application/xml and the response declares a XSL transformation, then the XSL transformation can be done by the server with http://localhost:8080/webapp/xslt?tplt=xml and the response will be the result of the XSL transformation insteado of the XML file.

  • Path info validator class: This is an advanced feature. By default a valid 2step URL is looks like http://localhost:8080/webapp?tplt=home&lang=en, but your applications may use the URL scheme that you wish changing the path info validator. For instance is possible to program a path info validator where the previous URL would have this new form: http://localhost:8080/webapp/en/home. See com.zentense.step2.PathInfoValidator for more information on this subject.


4.1.2. Access control

  • Authentication users stored in database: By default, when unchecked, all users with permissions are stored in access.properties file. When checked, users can also be stored in a database table.

  • Encrypt passwords: By default unchecked. When active, all users passwords in access control are stored as a MD5 hash. Otherwise passwords are stored as plain text.

  • Users table: Only has effect if Authentication users stored in database is checked. Tells which database table contains users for checking access.

  • Login row: Only has effect if Authentication users stored in database is checked. Tells which row of users' table contains user logins.

  • Password row: Only has effect if Authentication users stored in database is checked. Tells which row of users table contains user passwords.


4.1.3. Java compiler

  • External compiler: By default, default Java SDK is used. If you check this box, you can use another Java compiler. jikesfrom IBM, for instance, is several times faster than javac, and a good choice for huge projects.

  • External compiler command: Command (and options if needed) to execute external compiler.

  • Generate I18N files: If there are files with internationalized texts, this option overwrites them each compilation with all entries alphabetically ordered. It is useful for maintain files with lots of I18N text entries.


4.1.4. Database

  • JDBC Driver: The JDBC Driver class if you want to use a database in your application. There are JDBC drivers for virtually any existent database, so you will need the right one for your database. If you want to connect to MySQL using the official driver, you should put com.mysql.jdbc.Driver

  • Database URL: The JDBC database URL. It depends on the driver used. For the MySQL driver, for connecting to a MySQL database called zen3 on localhost it would be jdbc:mysql://localhost/zen3

  • Login and password: If the database access is authenticated, then put here your login and password.

  • Connection pool size: By default is 3. 2step creates a pool of database connections when is initiated, and reuses the same connections all the time. Here you can select the size of this pool. Notice that the size of the pool is equivalent to the maximum number of concurrent requests that this application will serve.

    So if you define a pool size of 1, then only 1 request is served at any given moment. If, while the server is serving this request, another one arrives, it is blocked till the first one ends, and then the second one is served. The server would serialize all the request. With a pool of 2 or more connections, both requests would be served in parallel. The total time to render both pages will be the same in both cases, but in the second one second user does not have to wait the first page to be finished for starting to see something.

    A value of 3 is more than enough for common applications. A typical page can take, to be rendered by the server, as little as less than 0.01 seconds, or as much as the calculations your application runs take. You would like to increase the pool size in a heavy loaded server.


4.1.5. Internationalization

  • Activate I18N: If this checkbox is active, then your application can use internationalized resources, and on every new session, 2step will try to obtain the list of accepted languages from the client, and select the language that best fits for that client.

    The internationalized resources, are properties text files that contain key-value pairs. There is a different file for each accepted language, and all the files must contain the same keys, but the values will be translated to the language of each file. This way, through the keyword i18n you can access this texts.

    This resources files must be placed in the subdirectory i18n of the application directory, and they are named this way: the texts file for spanish, is messages_es.properties, and the one for deutsch is messages_de.properties.

  • Accepted languages: This is a comma-separated list of accepted languages. For each language it will be the corresponding text file in the i18n directory. For accepting spanish and deutch put here es, de

  • Default language: When a new session arrives, 2step tries to guess if any of the accepted languages defined above matches with any of the accepted ones of the client browser. But if there is not any matching, then the default language is used.



4.2. Access control

This screen is quite complex. It is divided in four parts, so we will present here each part separately. But first, some words about 2step's access control. By default, all actions and templates are public and can be accessed without authentication. But if you put the modifier auth in the declaration of the action or template, 2step will render login page if session is not authenticated yet.

Here you can define users and passwords, groups of users, modules. For each name or module, you can define several allow or deny rules, granting or denying access to the resource identified by that name. The access control configuration is saved in the file access.properties, located in the application directory (this file is automatically created if it does not exist).

4.2.1. Users

At the top of the screen, there is the list of users. Users and their passwords can be stored in the access.properties file as well as in a database table. First kind of users are shown grey, while the ones at database, in black.

Here you see all the users stored in the properties file, and the users from the database that appears in any group or rule. This is this way because database users table may have thousands of users. Clicking on a user you can change its password, and clicking on the minus sign at the left of the name, the user is deleted. New users can be created and you can select where to store it (properties or database).

4.2.2. Groups

Next, is the list of groups. A group is a list of users, and a group cannot contain other groups. You can create, edit and delete groups at your own will.

4.2.3. Modules

Below the groups, you find the modules section. A module is a list of unit names. Each name identifies a unit, that is, a template or an action (you cannot differentiate in access control a action called foo from a template called foo as both are referred by the same name foo. You can assign rules to this modules and they are applied to all the names of that module.

When you create a module, you see the list of all available units that are not assigned to another module. Check the ones that you want in this module and name them. You can edit and delete modules as expected.

4.2.4. Allow / Deny rules

Finally there are the rules. There are two types of rules, ones that allow the access to the resource, and ones that deny it. A rule has two sides: the resource (a unit, a module name or a method) where the rule is applied (shown at the left), and the entity (the user or the group) for who this rule applies.

There are some wildcard rules. Rules for the resource all are wildcard rules that allow or deny access to all the resources. And rules for the entity all are wildcard rules that allow or deny access to all users.

So, the rule allow(all, admin) grants access to all the resources to user admin, while the rule allow(common, all) grants access to resource common to all users. The rule allow(all, all) grants all resources to all users, and deny(all, baduser) denies any access to user baduser.

4.2.4.1. Method invocation rules

2step allow to invoke methods on session objects remotely. This leads to security risks that must be taken into account. Invoke remotely a method is denied by default, but you can add rules for allowing some methods to be executed remotely (an URL like /webapp?bean=var&method=setFilterState&par1=name would try to execute method setFilterState with one parameter on variable var).

A method invocation rule is as the other ones, but the resource is formed by the name of the session variable and the name of a method separated by a dot. Wilcards are also allowed, so that allowing a entity to execute all.all is the same as allowing it to execute everything, allowing a entity to execute var.all is the same as allowing it to execute any method on variable called var, or allowing a entity to execute all.setFilterState is the same as allowing it to execute the method setFilterState on any variable.

4.2.5. Rule precedence

Checking if an entity has access to a resource is a matter of applying the rules in a determinated order. In the box below you can see in which order rules are applied. The first line means: Is there any allow rule for the resource name and current user? If the answer is true, then we know that the user is allowed to access that resource. Otherwise, we check second rule: Is there any deny rule for resource and name? If the answer is true, access is denied, or otherwise we go to the third rule. If we arrive to the 12th rule, then access is implicitly denied. 

1.  allow( name , user  ) ?
2.   deny( name , user  ) ?
7.  allow( name , group ) ?
8.   deny( name , group ) ?
3.  allow( name , all   ) ?
4.   deny( name , all   ) ?
5.  allow( all  , user  ) ?
6.   deny( all  , user  ) ?
9.  allow( all  , group ) ?
10.  deny( all  , group ) ?
11. allow( all  , all   ) ?
12.    ACCESS DENIED!!!



4.3. Constants

In this screen you can manage application constants. A constant is a key that has a value. You can access constants from your application using the keyword constant



   5. Log out

  Ends this administration session. This options is only visible in production mode, because in development there is no authentication, and has no much sense to log out.

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