Brazil project framework Developer Documentation Kenai-svn-r24

Welcome to the Brazil server developer documentation


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. 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. 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:

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)
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:

 main.handlers=first second
 first.setting=another value
 second.option=another value
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.

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

The Brazil Team

Version Kenai-svn-r24, Generated 08/18/09
Copyright (c) 2001-2009, Sun Microsystems.