Brazil project framework Developer Documentation Kenai-svn-r24

Welcome to the Brazil server developer documentation

See:
Description

Core Packages

sunlabs.brazil.filter	Filters are a type of handler, used by the filterHandler that can modify content after it has been obtained by another handler.
sunlabs.brazil.handler	This package contains a collection classes that implement the Handler interface for use with the Server package, along with several support classes.
sunlabs.brazil.properties	Classes for defining and using "smart" properties with Brazil.
sunlabs.brazil.server	Generic http protocol stack, essential handlers and drivers.
sunlabs.brazil.template	Template classes for use with TemplateHandler or TemplateFilter for filtering HTML and XML content.
sunlabs.brazil.util	Utility classes that are generically useful in Java language programs.
sunlabs.brazil.util.http	Utility classes for dealing with the HTTP protocol.
sunlabs.brazil.util.regexp	This package contains a converted-to-Java-language version of Henry Spencer's regular expression package contained in TCL version 8.0.

Packages requiring external jar files*

sunlabs.brazil.beanshell	Provide ways of integrating the Bean Shell scripting language into the Brazil project server.
sunlabs.brazil.derby	Provide ways of integrating the Derby (aka cloudscape) database into the Brazil project server.
sunlabs.brazil.email	Provide ways of integrating Email services into the Brazil project server.
sunlabs.brazil.exif	This package provides ways to extract EXIF data out of (mostly jpeg) images using: metadata-extractor-2.3.1.jar from here.
sunlabs.brazil.groovy	Provide ways of integrating the Groovy scripting language into the Brazil project server.
sunlabs.brazil.javascript	Provide ways of integrating the Javascript scripting language into the Brazil project server.
sunlabs.brazil.json	Integration of JSON, the JavaScipt Object Notation into the Brazil project server.
sunlabs.brazil.ldap	Provide ways of integrating LDAP into the Brazil project server.
sunlabs.brazil.python	Provide ways of integrating the Python scripting language into the Brazil project server.
sunlabs.brazil.servlet	Run a Brazil application as a Servlet.
sunlabs.brazil.ssh	Allow ssh (client) sessions to be manipulated via *ml tags.
sunlabs.brazil.ssl	Provide ways of integrating SSL into the Brazil project server.
sunlabs.brazil.tcl	Provide ways of integrating the TCL scripting language into the Brazil project server.
sunlabs.brazil.velocity	Integrates the Velocity template engine with the Brazil project server.
sunlabs.brazil.xmpp	Integration with Smack XMPP client library.

Other Packages

sunlabs.brazil.asterisk	Provide ways of integrating the the Brazil project server into the Asterisk PBX.
sunlabs.brazil.proxy	Handlers, filters, and utilities for using the Brazil project framework as an HTTP proxy.
sunlabs.brazil.session	A generic, extensible mechanism for managing session state.
sunlabs.brazil.sql	Provide ways of integrating the SQL database query language into the Brazil project server.
sunlabs.brazil.sunlabs	Experimental features that are used in the deployment of internal Brazil applications, but not considered part of the standard release.

Welcome to the Brazil server developer documentation

Introduction and Background

The Brazil server began as an extremely small footprint HTTP stack, originally designed to provide a URL based interface to smartcards, so the smartcards could be accessed more easily from an ordinary web browser.

Along the way it grew to provide a more flexible architecture for adding URL based interfaces to arbitrary applications and devices.

Architectural overview

The Brazil server features:

• A Simple extension API (called a Handler) using a delegation based object model.
• Dynamic loading of application functionality and configurations. The handlers that provide application functionality are resolved and loaded at run time.
• Mechanisms for composing application modules, encouraging code reuse and design orthogonality. Information specific to an entire application is gathered in one place, and made available to all of the handlers, simplifying server modification and configuration.

What you need to know to get started.

To use the server as part of your application, you will need one or more handlers. A handler is the kindred spirit to a servlet in Java Web Server terminology, but lighter weight. You may use one or more of the supplied handlers (see here for a summary), or write one or more of your own.

Writing a handler consists of creating a Java language class that implements the Handler interface, which consists of exactly two methods, Handler.init(Server, String) and Handler.respond(Request). The first is called once, when the server is initialized, the other on each http request.

For many applications, the entire functionality of the system can be encapsulated in one or more handlers. In these cases, the program may be started by the supplied Main program, by providing the name of your handler class and network port on the command line, as in:

    Java sunlabs.brazil.server.Main \
        -port 8080 \
        -handler my_handler_class_name

More sophisticated applications may wish to create their own main program, then start one or more instances of Server to start the http protocol stack running, listening on the network port (or ports) of their choosing. Look at the source code for the reflectHandler as a starting point for building your own handlers.

If your handler can be configured at run-time with different settings or operating parameters, then they can be appended to the command line in the form of name/value pairs, as in:

    java sunlabs.brazil.server.Main -handler my_handler_class_name \
        parameter_1 value_1   parameter_2 value_2 ...

The main program will put these name/value pairs into the Server.props field of the server object, which is passed as a parameter to the handler's init method.

Alternately, these command line parameters can placed in a Properties format file, and referenced via the -config flag of the Main program, as in:

  java sunlabs.brazil.server.Main -config my_config_file
  (contents of my_config_file)
  port=8080
  handler=some_name
  some_name.class=my_handler_class_name
  some_name.parameter_1=value_1
  some_name.parameter_2=value_2
  

The arbitrary token some_name is used as a prefix to indicate which properties belong to the handler. The only one required is some_name.class which tells the server which class to use as a handler. All other properties are supplied as parameters to the handler. See Main for a complete description of the sample main program.

Most applications will want to use multiple handlers, either written specifically for the application, or in combination with some of the handlers provided in the handler package. The Server class conspires with both the Handler.init(Server, String) method and the ChainHandler to allow multiple handlers to work together, define their own configuration parameters, and avoid the confusion of which configuration parameter belongs to what handler.

The ChainHandler, is the default mechanism used to run multiple handlers. It looks for a single configuration parameter, called handlers which contains a list of tokens, each of which refers to another handler to start. It can even refer to other instances of the chainHandler, enabling the creation of an arbitrary tree of handlers.

The chainhandler starts the other handlers, by instantiating them with newInstance() and invoking their init method. which is passed the corresponding token as the prefix parameter, The handler is expected to tack that prefix on to the front of each configuration parameter it uses before looking it up in Server.props.

Suppose an application uses two handlers, called A and B. The A handler looks for configuration parameters named setting and option, whereas the B handler is looking for options called option and other. The server that uses these two handlers might have a configuration file that looks like:

 handler=main
 main.class=sunlabs.brazil.server.ChainHandler
 main.handlers=first second
 first.class=A
 first.option=value
 first.setting=another value
 second.class=B
 second.option=another value
 second.other=none

The first line is interpreted by the server, which is instructed to use the ChainHandler (main.class). The ChainHandler looks at the main.handlers line, for the list of tokens that represent each handler it will run, in this case first and second. The ChainHandler then creates instances of both A and B, by examining the first.class and second.class entries. The handler A init method is called with first. as its prefix, whereas B is called with second. as the prefix parameter.

When A looks for its configuration parameters in Server.props, it looks for first.option and first.setting (not option and setting). In those cases where handlers with to share parameter names, such as the document root property of the FileHandler, by convention they use the empty prefix ("").

Once the content has been retrieved from a handler, it can be modified before being passed to the client. The FilterHandler is used to trap the generated content, then pass it to one of more filters Filter for modification.

Additional information

Many sample configurations are included in the Brazil.jar file in the "samples" directory, which may be unpacked with a command like jar xf brazil.jar samples.

The samples include both complete working applications (in their own sub-directories), and simple examples that demonstrate the operation of specific handlers and templates, in the simple directory, which is a good place to start.

• View selected sample applications

How to write a handler tutorial

Although many Web applications can be implemented by by combining combining and configuring several of the supplied handlers (see here for an example), it is expected that most applications will either create their own handlers (or modify existing ones), and then build their applications by combining their handlers with the ones supplied.

In this tutorial, we'll construct several simple java classes that extend the functionality of the Brazil system. Start here for the tutorial.

How to Combine Handlers

In constructing your application, it is common to combine one or more of the supplied handlers with custom handlers, created for a specific application. Indeed, many useful applications can be realized simply by combining the existing handlers in novel ways. Start here for the tutorial.

The Brazil Roadmap

There are lots of classes in the Brazil system. Some are designed to be used "as is" as part of server configurations, others are intended to be used by developers who are extending the system. The Brazil roadmap is an abbreviated index to some of the more important classes that are useful when first getting started.

The Brazil Development environment

Although the Brazil packages, in the form of one or more jar files may be used to build and link your application using the development of your choice, if you wish to build the software from the sources, you will need to understand the Brazil build system.

Other links

• Change log. A summary of all changes made to the system.
• Summary of Handler options.
• Summary of template tags and attributes.
• Highlights of differences from the previous release.
• *Many of the external jar files required by optional features are available at N-A-W-S sourceforge project site .

The Brazil Team

Stephen Uhler
Rinaldo DiGiorgio
alumni
Steve Drach
Guy Martin
Colin Stevens