Revision as of 23:59, 3 February 2010

Note: This is a forward-looking document and features discussed here are not implemented in the Trainz environment at the current time.

iTrainz servlets are persistent server processes that provide serverside functionality for iTrainz client applications. Servlets have the following properties:

• Written in TrainzScript.
• Run outside the Trainz game environment - this means that they do not have a user interface, or any standard Trainz game state such as a loaded map.
• Communicate with client applications via iTrainz.
• Communicate with external clients or external applications via HTTP.
• Only one servlet instance permitted per asset.
• Provide an administrative console for debugging and control.

Persistence

A persistent private data store is available to each servlet. It is the servlet's responsibility to maintain any persistent state by writing into the data store as appropriate. A servlet may be terminated without notice for a variety of reasons, and is expected to resume operations using the persistent data store after a restart.

Production Environment

The production runtime environment for iTrainz servlets is hosted on the Planet Auran servers. iTrainz servlets run in the production environment are sourced from the Download Station.

Installing/Uninstalling an iTrainz servlet

Prior to installing an iTrainz servlet, the servlet asset must be uploaded to the Download Station and approved. The content creator must then login to the http://servlet.auran.com/administrator page using their Planet Auran details. This page provides a list of the running servlets for that creator, their current status summary, and options to install or uninstall servlets.

Any servlet asset with no missing or faulty dependencies is eligible for installation. Once installed, the servlet is available in the "stopped" state.

Starting/Stopping an iTrainz servlet

A single click on a servlet status icon on the http://servlet.auran.com/administrator page is sufficient to start a servlet from the "stopped" state. Stopping a servlet is performed in a similar fashion, but requires confirmation.

Accessing the administrative console

Clicking on a servlet console icon on the http://servlet.auran.com/administrator page will open a javascript console window. Console output from the running servlet is output to this console. Lines entered in the console will be forwarded to the servlet after 'enter' is pressed.

Accessing the servlet log

Clicking on the servlet log icon will show any recent activity logged by the servlet. The log is not refreshed live, but the page may be refreshed to view any updates to the log. It is recommended that the administrative console is used if a regular refresh is necessary.

Fault Management

In the event of a fault occurs in the runtime environment or host hardware, servlets will be returned to the same state (running, or not) soon after the runtime environment is restored.

When a fault occurs in a servlet, the servlet is automatically stopped and restarted. This event will be written to the servlet log. Frequent or serious faults may result in the servlet being flagged with an error state. Once flagged, the creator must intervene to restart the servlet.

As iTrainz persists messages and servlets should be written to recover from unexpected restarts, a solitary failure event should be noticeable to the majority of users. Active web clients may be disconnected, however subsequent requests should succeed.

Web Clients

Web clients may access the servlet at http://servlet.auran.com/userid:contentid/ or any URL within that path. Named paths may be provided by Auran on request.

Quotas

iTrainz servlets have significantly higher iTrainz bandwidth allowances than regular iTrainz client applications. Exact limitations TBD and subject to change. iTrainz usage policy applies.

Servlets which consume significant CPU resources will be throttled. In extreme cases, this may cause the servlet to appear lagged to client queries. Servlets with no client activity may be suspended until client activity resumes. Servlets which do not respond to administrative control in a reasonable timeframe will be terminated.

The maximum size of a servlet (including all dependencies) may be limited. TBD.

The number of servlets run simultaneously by a particular creator may be limited. TBD.

Limits may be applied to the number of concurrent HTTP clients and the volume of HTTP data. TBD.

An upper limit may be applied to the volume of persistent storage available to a servlet. TBD.

Development Environment

Servlets may be run on a Trainz client installation using the TBD utility. This will provide a similar environment to that provided by the Planet Auran servers, but running on the localhost and using local content. The extended iTrainz quotas are not available in this scenario, so this is not suitable as a production server. At the current time, this client environment cannot be run simultaneously with Trainz on the same Planet Auran login.