|
Brazil project framework Developer DocumentationSee: Description
Welcome to the Brazil server developer documentation.Introduction and BackgroundThe 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 overviewThe Brazil server features:
What you need to know to get started.To use the server as part of your application, you will need to write one or more handlers. A handler is the kindred spirit to a servlet in Java Web Server terminology, but lighter weight.
Writing a handler consists of creating a Java language class that
implements the
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
Java sunlabs.brazil.server.Main \
-port 8080 \
-handler my_handler_class_name
More sophisticated applications may wish to create their own 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
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_2The 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 sunlabs.brazil.handler package.
The
The
The chainhandler starts the other handlers, by instantiating
them with newInstance() and invoking their init method.
which is passed the corresponding
token as the
Suppose an application uses two handlers, called A and B. The A handler
looks for configuration parameters named 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=noneThe 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
Once the content has been retrieved from a handler, it can be
modified before being passed to the client. The
How to write a handler tutorialAlthough 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 a handler for an X10 power-line interface, which will enable home automation through the web. Start here for the tutorial. How to Combine HandlersIn 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 Development environmentAlthough 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. The Brazil Team
Colin Stevens Stephen Uhler
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
