Brazil project Developer Documentation

Brazil project Developer DocumentationStephen A Uhler

Release 23

Table of Contents 1Welcome to the Brazil server developer documentation 1Introduction and Background 1Architectural overview 3Package sunlabsbrazilasterisk 4Class AsteriskAGIHandler 8Class AsteriskHandlerAmiStringMap 11Class AsteriskHandlerEventItem 14Class AsteriskHandlerEvents 16Class AsteriskHandler 22Package sunlabsbrazilbeanshell 23Class BeanShellHandler 26Class BeanShellServerTemplate 30Class BeanShellTemplate 33Package sunlabsbrazilderby 34Class DerbyServer 37Package sunlabsbrazilemail 38Class EmailTemplate 49Package sunlabsbrazilfilter 50Class CopyContentFilter 54Class ExecFilter 58Interface Filter 60Class FilterHandler 64Class MD5Filter 67Class PlainFilter 70Class ReFilter 74Class ReplaceFilter 78Class SessionFilter 83Class TemplateFilter 87Class UrlMapFilter 90Class UrlSessionFilter 94Package sunlabsbrazilgroovy 95Class GroovyServerTemplate 98Package sunlabsbrazilhandler 99Class AclSwitchHandler 102Class BasicAuthHandler 109Class CgiHandler 112Class ChainSawHandler 116Class ChownHandler 119Class ConfigFileHandler 122Class CookieSessionHandler 126Class DefaultFileHandler 129Class DeferredHandler 132Class DialogHandler 138Class DigestAuthHandler

041607Release 23 - i -

Table of ContentsBrazil project Developer Documentation SML-2006-0530

145Class DirectoryHandler

148Class DynamicConfigHandler

152Class GenericProxyHandler

157Class HomeDirHandler

160Class HtmlRewriter

172Class LogHandler

177Class MapPage

182Class MultiHostHandler

186Class MultiProxyHandler

190Class NotFoundHandler

193Class PollHandler

198Class PropertiesHandler

201Class ProxyPropertiesHandler

205Class PublishHandler

208Class PushHandlerSplit

211Class PushHandler

215Class RePollHandlerExtract

218Class RePollHandler

223Class ReflectHandler

226Class ResourceHandler

230Class ResourceLimitHandler

233Class RestartingMultiHostHandler

235Class RestrictClientHandler

238Class RolesHandler

242Class SMTPHandler

248Class SimpleSessionHandler

252Class SupplyHandler

255Class UrlMapperHandlerMapProperties

258Class UrlMapperHandler

261Class VirtualHostHandler

264Package sunlabsbraziljavascript

265Class JavaScriptTemplate

269Package sunlabsbrazilldap

270Class LDAPTemplate

274Package sunlabsbrazilproperties

275Class ExprProps

279Class ExprPropsHandler

282Class PropertiesList

296Interface SubstPropsHandlerConvert

297Class SubstPropsHandlerHtml

299Class SubstPropsHandlerLowerCase

301Class SubstPropsHandlerResub

303Class SubstPropsHandlerSubstProps

305Class SubstPropsHandlerUrl

307Class SubstPropsHandler

311Package sunlabsbrazilproxy

312Class CookieFilter

Release 23041607 - ii -

Brazil project Developer DocumentationTable of Contents SML-2006-0530

317Class HistoryFilter

322Class JunkBusterHandler

325Class ProxyHandler

330Interface UseProxy

331Package sunlabsbrazilpython

332Class PythonServerTemplate

335Package sunlabsbrazilserver

336Class ChainHandler

341Class FileHandler

347Interface Handler

349Class Main

353Class RequestHttpOutputStream

356Class Request

374Class Server

383Class TestRequest

386Package sunlabsbrazilservlet

388Class BServletRequestHttpOutputStream

391Class BServletRequest

395Class BServletServerSocket

400Class BServletSocket

409Class BrazilServlet

413Package sunlabsbrazilsession

414Class CacheManager

417Class PJamaSessionManager

418Interface PropertiesCacheManagerSaveable

420Class PropertiesCacheManager

424Class SessionManager

427Package sunlabsbrazilsql

428Class SqlTemplate

432Package sunlabsbrazilssl

433Class BasicSSLHandler

436Class CertHandler

440Class SslHandler

443Package sunlabsbrazilsunlabs

444Class AfterTemplate

446Class DateTemplate

448Class DelayHandler

451Class DigestTemplate

453Class ExecTemplate

456Class ExpContentTemplate

459Class FormHelpTemplate

463Class IdUniquificationTemplate

466Class ListTemplateMyList

473Class ListTemplate

477Class LockTemplate

480Class MiscTemplateGlobProperties

482Class MiscTemplate

041607Release 23 - iii -

490Class PlainTemplate

492Class PutHandler

495Class RemoteHostTemplate

497Class RestartHandler

500Class SnarfTemplate

503Class SourceTemplate

505Class StunnelHandler

508Class SubstAllTemplate

510Class TitleTemplate

512Class ValidateTemplateGlobFormat

514Class ValidateTemplateGlobProperties

516Class ValidateTemplate

520Class XmlTreeDefaultNodeName

522Class XmlTreeIllegalXmlException

525Class XmlTreeNode

529Interface XmlTreeNodeName

530Class XmlTreeXmlErrorInfo

532Class XmlTree

541Class XmlTreeTemplate

544Package sunlabsbraziltcl

545Class TclFilter

549Class TclHandler

552Class TclRePollHandler

555Class TclServerTemplate

559Package sunlabsbraziltemplate

560Class AddHeaderTemplate

562Class AllowGtTemplate

564Class BSLTemplate

575Class ChangedTemplate

579Class ContentTemplate

585Class DeCommentTemplate

587Class DebugTemplate

589Class DirectoryTemplate

593Class FormClientTemplate

597Class FormTemplate

601Class HighlightTemplate

606Class IncludeTemplate

609Class MacroTemplate

613Class ModifiedTemplate

616Class MultipartSetTemplate

621Class NoImageTemplate

623Class PropsTemplate

626Class QueueTemplateQueue

631Class QueueTemplateQueueItem

634Class QueueTemplate

641Class RedirectTemplate

643Class RewriteContext

Release 23041607 - iv -

651Class ScriptEvalTemplate

653Class SetTemplate

663Class TOCTemplate

665Class Template

668Class TemplateHandler

672Interface TemplateInterface

673Class TemplateRunner

677Class TemplateTemplate

679Class UrlNavBarTemplate

681Package sunlabsbrazilutil

682Class Base64

684Class Calculator

688Class ClockFormat

692Class ClockScan

694Class Format

699Class Glob

701Class Guid

703Class LexHTML

706Class LexML

713Class MatchString

716Interface SocketFactory

718Interface SortCompare

719Class Sort

721Class StringMap

730Package sunlabsbrazilutilhttp

731Class HttpInputStream

737Class HttpRequest

753Class HttpSocket

756Interface HttpSocketPool

758Class HttpUtil

763Class MimeHeaders

769Package sunlabsbrazilutilregexp

770Interface RegexpFilter

772Class Regexp

781Class Regsub

785Package sunlabsbrazilvelocity

786Class VelocityFilterVrequest

788Class VelocityFilterVserver

790Class VelocityFilter

795Configuration Parameter Summary

795AclSwitchHandler [p ]

795AsteriskHandler [p ]

796BSLTemplate [p ]

796BasicAuthHandler [p ]

797BasicSSLHandler [p ]

798BeanShellHandler [p ]

798BeanShellServerTemplate [p ]

041607Release 23 - v -

798BrazilServlet [p ]

799CacheManager [p ]

799CertHandler [p ]

799CgiHandler [p ]

800ChainHandler [p ]

800ChainSawHandler [p ]

800ChangedTemplate [p ]

801ChownHandler [p ]

801ConfigFileHandler [p ]

802ContentTemplate [p ]

802CookieFilter [p ]

803CookieSessionHandler [p ]

803CopyContentFilter [p ]

803DeCommentTemplate [p ]

804DebugTemplate [p ]

804DefaultFileHandler [p ]

804DeferredHandler [p ]

804DelayHandler [p ]

805DerbyServer [p ]

805DialogHandler [p ]

805DigestAuthHandler [p ]

806DirectoryHandler [p ]

806DirectoryTemplate [p ]

807DynamicConfigHandler [p ]

807ExecFilter [p ]

808ExecTemplate [p ]

808ExpContentTemplate [p ]

808ExprPropsHandler [p ]

808FileHandler [p ]

809FilterHandler [p ]

809GenericProxyHandler [p ]

810GroovyServerTemplate [p ]

810HighlightTemplate [p ]

811HistoryFilter [p ]

811HomeDirHandler [p ]

812JavaScriptTemplate [p ]

812JunkBusterHandler [p ]

812LDAPTemplate [p ]

814LogHandler [p ]

815MD5Filter [p ]

815MacroTemplate [p ]

816MatchString [p ]

816ModifiedTemplate [p ]

816MultiHostHandler [p ]

817MultipartSetTemplate [p ]

817NoImageTemplate [p ]

817NotFoundHandler [p ]

Release 23041607 - vi -

818PlainFilter [p ]

818PollHandler [p ]

819PropertiesCacheManager [p ]

820PropertiesHandler [p ]

820PropsTemplate [p ]

820ProxyHandler [p ]

821ProxyPropertiesHandler [p ]

821PublishHandler [p ]

821PushHandler [p ]

821PutHandler [p ]

821PythonServerTemplate [p ]

822QueueTemplate [p ]

822ReFilter [p ]

823RePollHandler [p ]

824ReplaceFilter [p ]

824ResourceHandler [p ]

824ResourceLimitHandler [p ]

825RestartHandler [p ]

825RestrictClientHandler [p ]

825RolesHandler [p ]

826SMTPHandler [p ]

826SessionFilter [p ]

826SetTemplate [p ]

827SimpleSessionHandler [p ]

828SnarfTemplate [p ]

828SqlTemplate [p ]

829SslHandler [p ]

829StunnelHandler [p ]

829SubstPropsHandler [p ]

830SubstPropsHandlerResub [p ]

830SupplyHandler [p ]

830TclFilter [p ]

831TclHandler [p ]

831TclRePollHandler [p ]

831TclServerTemplate [p ]

832TemplateFilter [p ]

832TitleTemplate [p ]

832UrlMapperHandler [p ]

833UrlNavBarTemplate [p ]

833VelocityFilter [p ]

834VirtualHostHandler [p ]

041607Release 23 - vii -

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 basedinterface 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 arbitraryapplications and devices

Over time it has become a modular full function web application development system

Supported PlatformsThe Brazil Framework will run on any Java VM version 11 or greater although some of the optional featuresavailable from external sources require more recent VMrsquos

Architectural overview

IntroductionTypical applications of the Brazil system combine one or more existing components together with customadditions consisting of one or more implementations of

handlers The primary extension interface which allows for the custom handling of URLrsquos

filters A special type of handler used in conjunction with the FilterHandler that permits content obtainedfrom other handlers to be rewritten

templates Are classes that work in conjunction with the TemplateFilter or TemplateHandler that allowhtmlXML content to be processed on a tag by tag basis

These custom or domain specific extensions interoperate with the supplied Handlers Filters and Templatesthat provide generic functionality to produce complete web applications

How to use this manualThe following pages consist of an alphabetized listing (by package) of the JavaDoc documentation for the Brazilsystem followed by a summary of the supplied Handlers and their configuration options There are differenttypes of classes documented here their function determines which portions of the javadoc documentation is mostrelevant

041607Release 23 - 1 -

Welcome to the Brazil server developer documentationBrazil project Developer Documentation SML-2006-0530

Classes whose names end in Handler Filter or Template provide functionality that may be usedas-is with an appropriate server configuration The most important part of the documentation for theseclasses are the configuration parameters these classes are rarely accessed directly from your Java codeMany applications of the Brazil framework have been implemented using only these classes with nocustom Java code required at all

Classes that define public interfaces such as Handler Filter and TemplateInterface as well asclasses whose instances are passed as parameters to those interfaces such as Server and RewriteContext define the primary mechanisms for extending the system by writing Handlers Filters or Templates The descriptions of the public methods and fields are most useful as they will bereferenced by your code

Many of the core capabilities of the system are accessed by class factories New implementations of thesecapabilities may be written and installed by sub-classing the default implementations of these capabilitiesand installing your own implementations as described in the documentation of the providedimplementations Examples include SessionManager used to control session state Guid to installyour own unique ID generator or SocketFactory to change the underlying client socket protocol

When writing new implementations of core services perusing the source code (which is included in thedistribution) is likely to be helpful as well as all of the some times subtle semantics of these classes are notproperly captured in the javadocs

Classes in the util package as well as classes in the handler or template packages that are notthemselves handlerss or templatess are utility or helper classes they provide commonly used capabilitiesthe descriptions of their public methods and fields would be most useful Some of the classes duplicatefunctionality that is now included in recent versions of the JDK but was not previously available They areretained (and used by the core system) to maximize the portability of the Brazil system across different Java versions

To get a better idea how the pieces fit together see the example applications included with the distribution

Release 23041607 - 2 -

Brazil project Developer DocumentationHow to use this manual SML-2006-0530

Package sunlabsbrazilasteriskProvide ways of integrating the the Brazil project server into the Asterisk PBX

Asterisk is an open source PBX that runs on Linux and Solaris (see asteriskorg) in this package providemechanisms for interacting with the Asterisk server (or servers) using the Asterisk public wire-protocols

041607Release 23 - 3 -

Package sunlabsbrazilasteriskBrazil project Developer Documentation SML-2006-0530

Class AsteriskAGIHandlersunlabsbrazilasterisk Class AsteriskAGIHandler

javalangObject | +--sunlabsbraziltemplateTemplate | +-- sunlabsbrazilasteriskAsteriskAGIHandler

All Implemented Interfaces Handler Runnable TemplateInterface

public class AsteriskAGIHandlerextends Templateimplements Handler Runnable

FAGI (fast AGI) handler and template for Asterisk This handlertemplate starts a server listening on the FAGIport Anytime it gets an agi request from it creates a dummy request object (sort of like TestRequest) tosimulate an http request reads a file implied by the request agi string and processes the file through thetemplate runner The template can be used to interact with via standard agi commands and the web via theSetTemplate and namespaces The template output is discarded (if debug is enables it is printed on the serverconsole) everything is done via side effect This allows us to interact with the ordinary template variables andnamespaces Irsquom still not sure how to deal with sessions so wersquoll use a different one for each uniqueid in the agirequest (This is a bad idea unless we delete completed sessions by hand)

(Implementation notes)This class implements 4 different threads - handlerinit to get the config params and start the listening socket -The thread that listens and accepts connections from - the threads that handle the incoming agi requests - thethreads that do the template stuff

Fields inherited from class sunlabsbraziltemplateTemplate

Constructor SummaryAsteriskAGIHandler ()

Release 23041607 - 4 -

Brazil project Developer DocumentationClass AsteriskAGIHandler SML-2006-0530

Method Summary boolean done (RewriteContext hr)

Close the socket connection

boolean init (RewriteContext hr) Open the socketrsquos streams at top of page

boolean init (Server server String prefix) Start a Listening socket thread and wait for AGI connections

boolean respond (Request request) We donrsquot handle any normal requests

void run () Either start a listening socket or handle an AGI request

void tag_agi (RewriteContext hr) Provide the rsquoagirsquo tag

Methods inherited from class javalangObject

equals getClass hashCode notify notifyAll toString wait wait wait

Constructor Detail

AsteriskAGIHandler

public AsteriskAGIHandler ()

Method Detail

public boolean init (Server server String prefix)

Start a Listening socket thread and wait for AGI connectionsSpecified by

init in interface HandlerTags copied from interface Handler Parameters

server - The HTTP server that created this Handler Typical Handler s will use Serverprops to obtain run-time configuration information

041607Release 23 - 5 -

Class AsteriskAGIHandlerBrazil project Developer Documentation SML-2006-0530

prefix - The handlers name The string this Handler may prepend to all of the keys that it uses toextract configuration information from Serverprops This is set (by the Server and ChainHandler ) to help avoid configuration parameter namespace collisions

Returnstrue if this Handler initialized successfully false otherwise If false is returned this Handler should not be used

respond

public boolean respond (Request request) throws IOException

We donrsquot handle any normal requestsSpecified by

respond in interface HandlerReturns

always false

public boolean init (RewriteContext hr)

Open the socketrsquos streams at top of page This will be used by the ltagigt callsOverrides

init in class Template

public boolean done (RewriteContext hr)

Close the socket connectionOverrides

done in class Template

tag_agi

public void tag_agi (RewriteContext hr)

Provide the rsquoagirsquo tag ltagi command=agi commandgt The result is placed in agi_result NOTE thethread running this instance doesnrsquot set any of the instance variables We get everything from hr

Release 23041607 - 6 -

public void run ()

Either start a listening socket or handle an AGI requestSpecified by

run in interface Runnable

041607Release 23 - 7 -

Class AsteriskHandlerAmiStringMapsunlabsbrazilasterisk Class AsteriskHandlerAmiStringMap

javalangObject | +--javautilDictionary | +--sunlabsbrazilutilStringMap | +-- sunlabsbrazilasteriskAsteriskHandlerAmiStringMap

Enclosing class AsteriskHandler

public static class AsteriskHandlerAmiStringMapextends StringMap

This class is built on top of the StringMap class and adds methods for reading Asterisk ManagerInterface replies

AMI responses are either

Mime-style headers followed by a blank line or The header Response follows followed by zero or more additional headers followed by one ormore lines of output followed by the line

--END COMMAND--

Unfortunately the first line of the following response can have a in it making it indistinguishablefrom another header [they shouldrsquoa added a blank line after the last header] We need to use someheuristics to figure out if itrsquos a header or data grumph

XXX to doAny time data follows the ActionID key (if present) will always be the last key before the datastarts We could use that or if the data consists of what looks like headers then just make themheaders and donrsquot stuff them into data which is sort-of what happens now

In the second case all the response data is put in a header called data

This is modelled after MimeHeaders

Release 23041607 - 8 -

Brazil project Developer DocumentationClass AsteriskHandlerAmiStringMap SML-2006-0530

Constructor SummaryAsteriskHandlerAmiStringMap ()

AsteriskHandlerAmiStringMap (StringMap map)

Method Summary String commandify (String id)

Turn an AmiMap into an asterisk command

static String commandify (StringMap map String id)

void read (HttpInputStream in)

Methods inherited from class sunlabsbrazilutilStringMap

add append clear elements get get get get getKey isEmpty keys put put put remove remove remove size toString

equals getClass hashCode notify notifyAll wait wait wait

Constructor Detail

AsteriskHandlerAmiStringMap

public AsteriskHandlerAmiStringMap ()

041607Release 23 - 9 -

Class AsteriskHandlerAmiStringMapBrazil project Developer Documentation SML-2006-0530

public AsteriskHandlerAmiStringMap (StringMap map)

Method Detail

public void read (HttpInputStream in) throws IOException

commandify

public String commandify (String id)

Turn an AmiMap into an asterisk command Make sure the Action keyword exists and is firstReturns

null if there wasnrsquot a valid command

commandify

public static String commandify (StringMap map String id)

Release 23041607 - 10 -

Class AsteriskHandlerEventItemsunlabsbrazilasterisk Class AsteriskHandlerEventItem

javalangObject | +-- sunlabsbrazilasteriskAsteriskHandlerEventItem

public static class AsteriskHandlerEventItemextends Object

Keep track of an event listener entry [Irsquom not sure what this should do yet] Each time an event arrives wetraverse the list checking for each regexp match When a match is found we send the event to all thelistening Qrsquos

Constructor SummaryAsteriskHandlerEventItem (String queue String key String exp String context String serverName)

Method Summary boolean addQ2Event (String queue String key String exp

String context String serverName) Add a new queue to an existing event

boolean remQEvent (String queue String key String exp) Remove an expQ pair

boolean send2Q(Dictionary event) Send an event to the qrsquos if there is a match

int size ()

String toString ()

String toString (String delim String delim2) Machine readable version

041607Release 23 - 11 -

Class AsteriskHandlerEventItemBrazil project Developer Documentation SML-2006-0530

Constructor Detail

AsteriskHandlerEventItem

public AsteriskHandlerEventItem (String queue String key String exp String context String serverName)

Method Detail

addQ2Event

public boolean addQ2Event (String queue String key String exp String context String serverName)

Add a new queue to an existing eventParameters

queue - The destination Qexp - The regular expression

Returnstrue if there is now an eventq match

remQEvent

public boolean remQEvent (String queue String key String exp)

Remove an expQ pair Return true if removedParameters

queue - The destination Q to remove (or all if null)key - The event key to match on (null for all keys)exp - The event re (or null for all rersquos)

Release 23041607 - 12 -

Brazil project Developer DocumentationClass AsteriskHandlerEventItem SML-2006-0530

Returnstrue if something was removed

public int size ()

send2Q

public boolean send2Q(Dictionary event)

Send an event to the qrsquos if there is a match XXX need to think about event format XXX if keycontains rsquorsquo or rsquorsquo do globbing

toString

public String toString ()

OverridestoString in class Object

toString

public String toString (String delim String delim2)

Machine readable version

041607Release 23 - 13 -

Class AsteriskHandlerEventssunlabsbrazilasterisk Class AsteriskHandlerEvents

javalangObject | +-- sunlabsbrazilasteriskAsteriskHandlerEvents

public static class AsteriskHandlerEventsextends Object

Class to manage the set of events This implementation maintains a vector of eventItems XXX We need todetect when the requester of an event goes away XXX without unregistering the event so we can remove itfor them

Constructor SummaryAsteriskHandlerEvents ()

Method Summary void addEvent (String queue String key String exp String context

String serverName) Add an event to the current set of events

boolean processEvents (Dictionary event) Send the event to all the proper Qrsquos

int removeEvents (String queue String key String exp) Remove events

String toString ()

Release 23041607 - 14 -

Brazil project Developer DocumentationClass AsteriskHandlerEvents SML-2006-0530

Constructor Detail

AsteriskHandlerEvents

public AsteriskHandlerEvents ()

Method Detail

addEvent

public void addEvent (String queue String key String exp String context String serverName)

Add an event to the current set of events If the event expression already exists add the queue name tothe existing event otherwise create a new event item

removeEvents

public int removeEvents (String queue String key String exp)

Remove events If a parameter is null it matches everything Warning if all three parameters are nullthen all events will be removed

processEvents

public boolean processEvents (Dictionary event)

Send the event to all the proper Qrsquos

toString

041607Release 23 - 15 -

Class AsteriskHandlerEventsBrazil project Developer Documentation SML-2006-0530

Class AsteriskHandlersunlabsbrazilasterisk Class AsteriskHandler

javalangObject | +--sunlabsbraziltemplateTemplate | +-- sunlabsbrazilasteriskAsteriskHandler

All Implemented Interfaces Handler TemplateInterface

public class AsteriskHandlerextends Templateimplements Handler

Connect to asterisk manager api There is one connection per server This is used both to issue Commandsto Asterisk via the manager interface and to register for and receive asynchronous event notifications

ltregister queue=xxx key=xxx pattern=xxx [context=xxx server=xxx]gt - register interest in a manager event (or events) All generated events will be available with ltdequeue name=xxx gt where the name parameter of the ltdequeuegt matches the queue parameter of ltregistergt ltunregister queue=xxx key=xxxgt - unregister interest in a previously registered event ltenqueue name=queue from=my-q gt - Send an command to the manager interface queue is the name specified in the handler queue parameter The enqueuersquod data must have an action key The result of the command is obtained by ltdequeue name=my-q gt where my-q is the from attribute of the corrosponding ltenqueuegt ltamicommand server=xxx action=xxx gt - A syncronous version of the ltenqueuegt ltdequeuegt above See below for details

Release 23041607 - 16 -

Brazil project Developer DocumentationClass AsteriskHandler SML-2006-0530

Inner Class Summarystatic class AsteriskHandlerAmiStringMap

This class is built on top of the StringMap class and adds methods for readingAsterisk ManagerInterface replies

static class AsteriskHandlerEventItem Keep track of an event listener entry

static class AsteriskHandlerEvents Class to manage the set of events

Constructor SummaryAsteriskHandler ()

041607Release 23 - 17 -

Class AsteriskHandlerBrazil project Developer Documentation SML-2006-0530

Method Summarystatic void addEvent (String queue String key String exp

String context String serverName) Java access to adding event registrations

boolean init (Server server String prefix) Remember the host port id and password for an asterisk manager connection

static int removeEvents (String queue String key String exp) java access to removing event registrations

boolean respond (Request request) The handler only registers servers

void tag_amicommand (RewriteContext hr) Issue a synchronous command to the Asterisk AMI interface

void tag_asterisk (RewriteContext hr) This only emits diagnostic information to stdout

void tag_register (RewriteContext hr) Register an event

void tag_unregister (RewriteContext hr) Unregister an event (or events)

Methods inherited from class sunlabsbraziltemplateTemplate

done init

Constructor Detail

AsteriskHandler

public AsteriskHandler ()

Release 23041607 - 18 -

Method Detail

Remember the host port id and password for an asterisk manager connection We donrsquot require thatthe asterisk server actually be running at server startup time We will try hard to reconnect to the serverif it goes away queue

The name of the Q to send manager commands to using the ltenqueue name=queue gt If notspecifies the hostport combination is used

server The serverport to use to contact the asterisk server

userid password The Manager credentials

debug=true|false turn on more diagnostics on the console depending on the current server logging level at 3keep alives are logged at 4 all events are logged and at 5 even more stuff is logged

keepalive=n If set this handler will issue a keep-alive every n seconds to the Asterisk Server If thekeep-alive fails a new connection will be attempted with the Asterisk server

retry=n Set the number of seconds to wait before retrying a broken connection to an asterisk server(defaults to 10)

To communicate with multiple asterisk servers each should have their own handler instance Serversare distinguished when sending commands to them via the queue parameter which should bedifferent for each server Alternately the ltamicommandgt server parameter (which is the same as theserver queue name) may be used

When using multiple servers only one of the server handler configurations should be listed as atemplate (there can only be one template instance for a given entity) which server doesnrsquot matter asevents get registered for all servers (the server attribute of the response determines where it camefrom) As above commands to a server are distinquished with either the queue or server attributesdepending on whether the command Qs are used directly or the ltamicommandgt template is used

To DoFigure out where to send unregistered events such as reloadSpecified by

server - The HTTP server that created this Handler Typical Handler s will use Serverprops to obtain run-time configuration informationprefix - The handlers name The string this Handler may prepend to all of the keys that ituses to extract configuration information from Serverprops This is set (by the Server and

041607Release 23 - 19 -

ChainHandler ) to help avoid configuration parameter namespace collisionsReturns

true if this Handler initialized successfully false otherwise If false is returned this Handler should not be used

respond

The handler only registers servers No requests are handled Use ltregistergt in a template insteadSpecified by

respond in interface HandlerTags copied from interface Handler Parameters

request - The Request object that represents the HTTP requestReturns

true if the request was handled A request was handled if a response was supplied to the clienttypically by calling RequestsendResponse() or RequestsendError

ThrowsIOException - if there was an IO error while sending the response to the client Typically in thatcase the Server will (try to) send an error message to the client and then close the clientrsquosconnection

The IOException should not be used to silently ignore problems such as being unable toaccess some server-side resource (for example getting a FileNotFoundException due tonot being able to open a file) In that case the Handler rsquos duty is to turn that IOExceptioninto a HTTP response indicating in this case that a file could not be found

tag_asterisk

public void tag_asterisk (RewriteContext hr)

This only emits diagnostic information to stdout

tag_amicommand

public void tag_amicommand (RewriteContext hr)

Issue a synchronous command to the Asterisk AMI interface This is a convenience for usingltenqueuegt and ltdequeuegt directly

Attributes server

The Asterisk serverrsquos Q (required)

Release 23041607 - 20 -

action The action to perform

variable=value one of the variables needed by the action (There is a fixed list See the manager docs for moredetail)

timeout The max time to wait for a response

prepend What to prepend all the results too

tag_register

public void tag_register (RewriteContext hr)

Register an event

ltregister queue=xxx key=xxx exp=xxx [context=xxx server=xxx]gt queue The Q name to send the results to key The manager response key to match on Use for all keys exp A regular expression that matches a key value context If specified only events with this context are considered server If specified only events from this server are considered The server matches the Server item in the event and is the server name followed by a then the port number (eg pbxcom5038)

addEvent

public static void addEvent (String queue String key String exp String context String serverName)

Java access to adding event registrations

tag_unregister

public void tag_unregister (RewriteContext hr)

Unregister an event (or events) Match on queue exp and key

removeEvents

public static int removeEvents (String queue String key String exp)

java access to removing event registrations

041607Release 23 - 21 -

Package sunlabsbrazilbeanshellProvide ways of integrating the Bean Shell scripting language into the Brazil project server

Files in this package depend upon the beanshelljar files which may be downloaded from wwwbeanshellorg

Release 23041607 - 22 -

Brazil project Developer DocumentationPackage sunlabsbrazilbeanshell SML-2006-0530

Class BeanShellHandlersunlabsbrazilbeanshell Class BeanShellHandler

javalangObject | +-- sunlabsbrazilbeanshellBeanShellHandler

All Implemented Interfaces Handler

public class BeanShellHandlerextends Objectimplements Handler

The BeanShellHandler permits handlers to be written in beanshell

The reason one would write a BeanShell handler instead of coding the handler directly in Java is for easeof handler development and maintanence a BeanShell handler may be modified at will while the server isrunning permitting rapid development Once functional the code is easily converted into a traditionalhandler

The beanshell script is expected to contain both init and respond methods which are invoked by theserver just like an ordinary handler script

The name of the BeanShell script to use as the handler Normally the script is read only once (defaultsto prefixbsh)

root The script directory if the script is a relative file name If the root property under the prefix is notfound the global root property is used If the global root property is not found the currentdirectory is used

debug If this configuration parameter is present the script is re-read on each request and a new interperteris created and initialized The call to init is deferred until request time and called before each call to respond

This allows beanshell scripts to be debugged interatively from scratch

Constructor SummaryBeanShellHandler ()

041607Release 23 - 23 -

Class BeanShellHandlerBrazil project Developer Documentation SML-2006-0530

Method Summary boolean init (Server server String prefix)

Initializes the handler

boolean respond (Request request) Responds to an HTTP request

Constructor Detail

BeanShellHandler

public BeanShellHandler ()

Method Detail

Description copied from interface Handler Initializes the handlerSpecified by

server - The HTTP server that created this Handler Typical Handler s will use Serverprops to obtain run-time configuration informationprefix - The handlers name The string this Handler may prepend to all of the keys that ituses to extract configuration information from Serverprops This is set (by the Server and ChainHandler ) to help avoid configuration parameter namespace collisions

Release 23041607 - 24 -

Brazil project Developer DocumentationClass BeanShellHandler SML-2006-0530

respond

Description copied from interface Handler Responds to an HTTP requestSpecified by

041607Release 23 - 25 -

Class BeanShellServerTemplatesunlabsbrazilbeanshell Class BeanShellServerTemplate

javalangObject | +--sunlabsbraziltemplateTemplate | +-- sunlabsbrazilbeanshellBeanShellServerTemplate

All Implemented Interfaces TemplateInterface

Direct Known Subclasses BeanShellTemplate

public class BeanShellServerTemplateextends Template

The BeanShellServerTemplate looks for one of the starting tags ltserver language=beanshellgt ltbeanshellgt or ltbshgt in an HTML page and treats thefollowing data up to the corresponding ending tag ( ltservergt ltbeanshellgt or ltbshgt ) as aBeanShell script to evaluate For information on BeanShell see wwwbeanshellorg

The reason that BeanShell scripts are included in an HTML page is usually to generate dynamic server-sidecontent After running this template everything between and including the starting tag and and the endingtag is replaced by all output written to the BeanShell output stream (if any)

All BeanShell fragments within a given page are evaluated in the same BeanShell interpreter TheBeanShell interpreter actually lives for the entire duration of this Template object so the user canimplement persistence across requests

The following configuration parameters are used to initialize this template script

The name of the BeanShell script to evaluate when the interpreter is created This script is onlyevaluated when the interpreter is created not on every request The variables prefix and serverare set before this file is evaluated and are references to the parameters passed to a handler initmethod

root The document root if the script is a relative file name If the root property under the template prefixis not found the global root property is used If the global root property is not found the currentdirectory is used

debug If this configuration parameter is present this class replaces the starting and ending tags withcomments so the user can keep track of where the dynamically generated content is coming from byexamining the comments in the resultant HTML document By default the starting and ending tags arecompletely eliminated from the HTML document rather than changed into comments

Release 23041607 - 26 -

Brazil project Developer DocumentationClass BeanShellServerTemplate SML-2006-0530

Before evaluating each HTML document this class sets variables in the BeanShell interpreter which can beused to interact back with Java to do things like set the response headers request

Exposes the Request Java object It is set anew at each request prefix

Exposes the handler prefix String server

Exposes the handler Server object If the attribute eval is present as an attribute all constructs off the form $ are substituted beforeprocessing the script

Herersquos a simple example of a BeanShell template

lthtmlgt ltheadgt lttitlegtBeanShell Exampleslttitlegt ltheadgt ltbodygt The global variables ltcodegtrequestltcodegt ltcodegtprefixltcodegt and ltcodegtserverltcodegt are already defined Herersquos how to add a new property ltbshgt sum = 3 + 4 + 5 requestpropsput(sum IntegertoString(sum)) ltbshgt And herersquos a way to list the properties contained in the request lttablegt ltbshgt e = requestpropspropertyNames() while (ehasMoreElements()) name = enextElement() value = requestpropsgetProperty(name) print(lttrgtlttdgt + name + lttdgtlttdgt + value + lttdgtlttrgt) ltbshgt lttablegt ltbodygt lthtmlgt

Constructor SummaryBeanShellServerTemplate ()

041607Release 23 - 27 -

Class BeanShellServerTemplateBrazil project Developer Documentation SML-2006-0530

Method Summary boolean init (RewriteContext hr)

Called at the beginning of each HTML document that this BeanShellServerTemplate is asked to process

void tag_beanshell (RewriteContext hr) Processes the ltbeanshellgt tag

void tag_bsh (RewriteContext hr) Processes the ltbshgt tag

void tag_server (RewriteContext hr) Processes the ltservergt tag

Constructor Detail

BeanShellServerTemplate

public BeanShellServerTemplate ()

Method Detail

Called at the beginning of each HTML document that this BeanShellServerTemplate is askedto process

Release 23041607 - 28 -

The first time this method is called the initialization script is sourced into the interpreter based on theconfiguration properties in the RequestOverrides

init in class TemplateParameters

hr - The request and associated HTML document that will be processedReturns

true interpreter was successfully initialized false otherwise About the only way that theinitialization could fail would be due to an error sourcing the initialization script If false isreturned an error message is logged

tag_server

public void tag_server (RewriteContext hr)

Processes the ltservergt tag Substitutes the result of evaluating the following BeanShell script intothe resultant HTML documentParameters

hr - The request and associated HTML document that will be processed

tag_beanshell

public void tag_beanshell (RewriteContext hr)

Processes the ltbeanshellgt tag Substitutes the result of evaluating the following BeanShell scriptinto the resultant HTML documentParameters

tag_bsh

public void tag_bsh (RewriteContext hr)

Processes the ltbshgt tag Substitutes the result of evaluating the following BeanShell script into theresultant HTML documentParameters

041607Release 23 - 29 -

Class BeanShellTemplatesunlabsbrazilbeanshell Class BeanShellTemplate

javalangObject | +--sunlabsbraziltemplateTemplate | +--sunlabsbrazilbeanshellBeanShellServerTemplate | +-- sunlabsbrazilbeanshellBeanShellTemplate

public class BeanShellTemplateextends BeanShellServerTemplate

Template to define new templates in beanshell and use them later on in the current session (or page) Thisadds to the capability of the template in the following way The variable tagMap a Properties object may be used to associate bsh code with a tag

tagMapput(mytagdo_mytag())

will cause the method do_mytag() to be called in response to ltmytaggt The variable rewriteContextwill be available to access the attributes of the tag

Field Summary Properties tagMap

Constructor SummaryBeanShellTemplate ()

Release 23041607 - 30 -

Brazil project Developer DocumentationClass BeanShellTemplate SML-2006-0530

Method Summary void defaultTag (RewriteContext hr)

if a mapping exists for this tag run the code

Methods inherited from class sunlabsbrazilbeanshellBeanShellServerTemplate

init tag_beanshell tag_bsh tag_server

Field Detail

tagMap

public Properties tagMap

Constructor Detail

BeanShellTemplate

public BeanShellTemplate ()

Method Detail

defaultTag

041607Release 23 - 31 -

Class BeanShellTemplateBrazil project Developer Documentation SML-2006-0530

public void defaultTag (RewriteContext hr)

Release 23041607 - 32 -

Package sunlabsbrazilderbyProvide ways of integrating the Derby (aka cloudscape) database into the Brazil project server

Files in this package depend upon the Derby database system and require one or both of derbyjar and derbynetjar Although Brazil will run with versions of the Java JDK that are at least version 11Derby requires at least 14 (or 13 with additional jar files)

041607Release 23 - 33 -

Package sunlabsbrazilderbyBrazil project Developer Documentation SML-2006-0530

Class DerbyServersunlabsbrazilderby Class DerbyServer

javalangObject | +-- sunlabsbrazilderbyDerbyServer

public class DerbyServerextends Objectimplements Handler

Template for starting derby in network server mode port

The port the server will listen on (defaults to 1527) log

If true log connections

Constructor SummaryDerbyServer ()

static boolean isReady (orgapachederbydrdaNetworkServerControl nsc)

Release 23041607 - 34 -

Brazil project Developer DocumentationClass DerbyServer SML-2006-0530

Constructor Detail

DerbyServer

public DerbyServer ()

Method Detail

isReady

public static boolean isReady (orgapachederbydrdaNetworkServerControl nsc)

respond

respond in interface HandlerTags copied from interface Handler

041607Release 23 - 35 -

Class DerbyServerBrazil project Developer Documentation SML-2006-0530

Parametersrequest - The Request object that represents the HTTP request

Returnstrue if the request was handled A request was handled if a response was supplied to the clienttypically by calling RequestsendResponse() or RequestsendError

Release 23041607 - 36 -

Package sunlabsbrazilemailProvide ways of integrating Email services into the Brazil project server

Files in this package depend upon the Java Mail API a sample implementation may be downloaded from wwwjavasoftcom

041607Release 23 - 37 -

Package sunlabsbrazilemailBrazil project Developer Documentation SML-2006-0530

Class EmailTemplatesunlabsbrazilemail Class EmailTemplate

javalangObject | +--sunlabsbraziltemplateTemplate | +-- sunlabsbrazilemailEmailTemplate

All Implemented Interfaces Filter Handler TemplateInterface

public class EmailTemplateextends Templateimplements Filter

The EmailTemplate takes an HTML document with embedded Email markup tags in it and evaluatesthose special tags to produce resulting properties that allow email readingcomposing functionality to beembedded within the document

The email functionality is implemented using four tags ltemailgt ltfoldergt ltmessagegt ltsendmailgt

The ltemailgt tag handles rsquostate controlrsquo The ltfoldergt tag provides a means to manipulate mailfolders The ltmessagegt tag provides viewing capabilities for email messages The ltsendmailgt tagallows outgoing messages to be sent via SMTP There is an additional tag (ltforcetimeoutgt ) that isused mainly for debugging

ltemailgt TAGThe ltemailgt tag provides rsquostate controlrsquo for the connection to the email server It handles opening andclosing the connection as well as providing authentication parameters to the server The general format ofthe ltemailgt tag is as follows

ltemail server=servername user=username password=userpassword action=[openclose] onError=somefilehtml connhandle=xyzgt

The connhandle parameter is optional and is used to be able to identify a unique server connection if morethan one ltemailgt tag is present in an HTML page (for example an email client that connects to morethan one email server to retrieve messages) The connhandle parameter is also used as the prefix forproperties returned from this and all of the email tags See PropsTemplate for more information on the ltpropertygt tag If no connhandle is present the properties returned are prefixed with the identifier usedfor the EmailTemplate in the configuration file The string prefix will be used throughout this document

Release 23041607 - 38 -

Brazil project Developer DocumentationClass EmailTemplate SML-2006-0530

to refer to this prepended string

Note that although server user and password are not listed as optional they can be left out after their firstuse For example after performing an action=open command the connection to the server can be closedwith the following command

ltemail action=closegt

The onError parameter is also optional but if present will give a location that the HTML client expects tobe redirected to in case of a fatal error within the processing for this tag In an error condition thisparameter does an implicit abort on all further processing of the HTML page

ltfoldergt TAGThe ltfoldergt tag provides functionality necessary to manipulate email folders It allows for the selectionof a particular folder listing of all folders within a folder directory as well as for other utility functionsThe general format of the ltfoldergt tag is as follows

ltfolder dir=xyz foldername=[INBOXanyfoldername] action=[listpurgemsgcountcreatedelete] onError=somefilehtml connhandle=xyzgt

The onError parameter is optional but if present will give a location that the HTML client expects to beredirected to in case of a fatal error within the processing for this tag In an error condition this parameterdoes an implicit abort on all further processing of the HTML page

The connhandle parameter is also optional and its use is specified in the documentation for the ltemailgttag

The dir parameter is used to establish a base directory where a userrsquos email folders reside For example onsome UNIX systems this is homeusernameMail

The foldername parameter is used to specify a foldername to operate on for the various operations (except action=list)

The action=list operation will create a list all mail folders within the directory specified by dir This list isreturned in property prefix folders - where each folder is delimited by the delim character whichdefaults to An optional glob attribute restircts the folders to those matching the glob pattern

The action=msgcount operation returns the total count of messages and the count of new messages in theselected folder in the following properties

prefix totalmsgcountprefix newmsgcount

This operation works on either a specified folder name (if provided) or the last selected folder

041607Release 23 - 39 -

Class EmailTemplateBrazil project Developer Documentation SML-2006-0530

The action=create operation creates a new folder with the name given The name of the folder is requiredbut the dir parameter is optional If not specified the current default directory will be used as the root location ofthe new folder

The action=delete operation deletes the named folder The name of the folder is required but the dirparameter is optional If not given the tag assumes that the folder to be deleted is located in the default directory

ltmessagegt TAGThe ltmessagegt tag is the workhorse of the Brazil email suite It provides the ability to get messageheader listings and to retrievedeleterefile individual messages and their attachments The general format of the ltmessagegt tag is as follows

ltmessage action=[getheadersgetnewheadersgetmsgdeletemsgundeletemsgrefilemsg] startmsg=nnn msglimit=nnn msgnum=n n n headerlist=From To Date foldername=xyz refilefolder=xyz onError=somefilehtml connhandle=xyzgt

The foldername parameter is required for all operations so that multiple open folders can be supported inseperate browser windows

The action=getheaders operation uses the headerlist parameter to determine which header values to retrievefor each message The header names in this list are case-sensitive If headerlist isnrsquot present ALL headerswill be retrieved This operation takes the optional parameters msglimit andor startmsg If msglimit isspecified without startmsg the headers returned will be the last msglimit number

The action=getnewheaders operation takes all of the same parameters as the action=getheaders operationexcept msglimit and returns values in the same properties listed below As its name suggests however itonly returns header information for the newly arrived messages in the folder

The header listing information is returned in the following properties

prefix nmsgnum - where rsquonrsquo = 123 (this is the msg number as defined by the mail server)

prefix nmsgstatus (this is either a rsquoUrsquo for unread an rsquoNrsquo for new a rsquoRrsquo for read or a rsquoDrsquo fordeleted)

prefix nHeadername - where rsquoHeadernamersquo = one of the header names returned or one of thosewithin the headerlist parameter (for example prefix 1From )

prefix nHeadernamen - where rsquoHeadernamersquo = one of the header names returned or one of thosewithin the headerlist parameter and rsquonrsquo = msg number (This format is only returned for headers that occurmultiple times in an email message with unique values (such as rsquoReceivedrsquo) Also returned in this case is a

Release 23041607 - 40 -

property named prefix nHeadernamecount which contains the enumerated count of themultivalue header

prefix n[ToFromCc] - This is a special case property that returns a comma seperated list ofrfc822 style (userdomain) addresses for the particular header (ToFromCc) that is used to name the property

prefix n[ToFromCc]addressn - This is a special case property that is returned for headersthat are used for addresses (ToFromCc) This property contains the rfc822 rsquouserdomainrsquo portion of theheader Since it is a multivalue header (like Received) it also has a count portion (the last rsquonrsquo) representing anenumeration of which address it was in the header (eg rsquo0 1 2rsquo)

prefix n[ToFromCc]personaln - This is a special case property that corresponds to thersquoaddressrsquo property above It contains the rsquoJoe A Userrsquo portion of the address It is also a multivalue property likeaddress Also returned in these cases is a property named prefix nTocount which contains theenumerated count of the multivalue header (ToFromCc)

prefix nDate - This is a special case property that returns the message sent date as a stringrepresentation

prefix nDatestamp - This is a special case property that returns the message sent date as a stringrepresentation of the number of seconds elapsed since the epoch (Jan 1 1970) This is useful in providingadditional formatting via the Brazil DateTemplate

Both of the above properties are returned for every rsquoDatersquo header requested in the action=getheadersoperation

prefix nmsgindex (this contains a list of the msg numbers - for example rsquo1 2 3 4 rsquo - this is useful initerating over the properties returned here with the BSLTemplate ltforeachgt tag)

The action=getmsg operation requires the msgnum parameter and returns the following properties

prefix msgnum (contains the message number)

prefix nHeadername - where rsquoHeadernamersquo = one of the names within the headerlist parameter andrsquonrsquo represents the msgnum (multi-value headers like rsquoReceivedrsquo are handled in the same manner as describedabove for action=getheaders)

prefix nbody (contains the text of the email msg (if available))

prefix nmsgmimetype (contains the string that specifies what MIME type the message is - useful fordeciding if yoursquoll need to convert plaintext to HTML before displaying it)

prefix njpartname - where rsquonrsquo is the msgnum and rsquojrsquo is a part number (for multipartmessagesattachments) (this contains the text string name of the multipart attachment)

prefix njparturl - where rsquonrsquo is the msgnum and rsquojrsquo is a part number (for multipartmessagesattachments) (this contains the URL that is needed to retrieve the multipart attachment - this URL canbe used in an lthrefgt or ltformgt tag)

041607Release 23 - 41 -

prefix npartcount (this contains a list of the part numbers and is useful for iterating over the partsproperties with the BSLTemplate ltforeachgt tag)

The action=deletemsg and action=undeletemsg operations requires the msgnum parameter which cancontain either a single message number or a space seperated list (eg rsquo1 2 3 4rsquo) of numbers

The action=refilemsg operation requires the msgnum and refilefolder parameters The value of refilefolderis a relative path from the dir parameter value provided in the ltfoldergt tag The msgnum parameter herecan also accept a space seperated list (as in the action=deletemsg tag)

ltsendmailgt TAGThe ltsendmailgt tag provides the ability to send outgoing email messages using the SMTP protocol Thesimplest form of the ltsendmailgt tag is as follows

ltsendmail to=userdomain cc=userdomain bcc=userdomain from=userdomain subject=test subject body=msg text onError=somefilehtml connhandle=xyzgt

This form of the tag provides basic functionality (no attachments) to send simple messages The completeform of the tag is as follows

ltsendmail to=userdomain cc=userdomain from=userdomain subject=test subject body=msg text onError=somefilehtml connhandle=xyzgt ltpart body=partdata name=bodypartfilename encoding=none|qp|base64 content-type=mimetypegt ltpart gt ltsendmailgt

This form of the tag allows attachments to be added to outgoing messages (via the ltpartgt tag The ltpartgttag requires parameters for the actual data for each part a filename (optional) an encoding type and acontent-type (optional)

The cc parameter is also optional

The from subject and body parameters should all be set to their respective values

In the event of an error during an attempt to send a message (as denoted by a rsquomailErrorrsquo property being set(see Error Handling)) the following property will be set

prefix sendmailerror - contains the specific reason that the sending of this message failed

ltforcetimeoutgt TAG

Release 23041607 - 42 -

This tag provides the ability to rsquoforcersquo a timeout of the connection to the email server It is generally onlyused for debugging purposes The complete form of the tag is as follows

ltforcetimeout connhandle=xyzgt

After this tag is processed calls to any of the other tags will result in errors being generated (see ErrorHandling below)

Error HandlingIn the case of a fatal error (one that requires re-authentication with the email server) during any emailoperation the following property is set (unless you used the per tag rsquoonErrorrsquo parameter for error handling)

prefix fatalMailError - this contains a string with the error message returned from the emailserver

Some non-fatal errors may be returned during the processing of any of the tags and these are returned in thefollowing property (note that these are returned regardless of the existence of the rsquoonErrorrsquo parameter in aparticular tag)

prefix mailError - this contains a string with the non-fatal error message returned from the emailserver

Constructor SummaryEmailTemplate ()

041607Release 23 - 43 -

If we run off the end of the page but there is email pending to be sent send it anyway

byte[] filter (Request request MimeHeaders headers byte[] content) Filters the content generated by the wrapped Handler

boolean init (RewriteContext hr) Called before this template processes any tags

boolean init (Server server String prefix) Initializes the handler

boolean shouldFilter (Request request MimeHeaders headers) Gives this Filter the chance to examine the HTTP response headers from the wrapped Handler before the content has been retrieved

void tag_email (RewriteContext hr) Handles the ltemailgt tag

void tag_folder (RewriteContext hr) Handles the ltfoldergt tag

void tag_forcetimeout (RewriteContext hr) The ltforcetimeoutgt tag will cause an immediate timeout of the connection to the email server

void tag_message (RewriteContext hr) Handles the ltmessagegt tag

void tag_part (RewriteContext hr) Handles the ltpartgt tag

void tag_sendmail (RewriteContext hr) Handles the ltsendmailgt tag

void tag_slash_sendmail (RewriteContext hr) Handles the ltsendmailgt tag

Release 23041607 - 44 -

Constructor Detail

EmailTemplate

public EmailTemplate ()

Method Detail

shouldFilter

public boolean shouldFilter (Request request MimeHeaders headers)

Description copied from interface Filter Gives this Filter the chance to examine the HTTP response headers from the wrapped Handler before the content has been retrieved

If this Filter does want to examine and possibly rewrite the content it should return true oncethe content is available the filter method will be invoked For instance if this Filter is onlyinterested in rewriting texthtml pages it should return false if the Content-Type isimagejpeg If all filters return false for the shouldFilter method the FilterHandler canswitch to a more effient mechanism of delivering content to the client

The MIME headers may also be modified by this Filter for instance to change the Content-Typeof a web page The Content-Length will automatically be computedSpecified by

shouldFilter in interface FilterTags copied from interface Filter Parameters

request - The in-progress HTTP requestheaders - The MIME headers generated by the wrapped Handler

Returnstrue if this filter would like to examine and possibly rewrite the content false otherwise

filter

public byte[] filter (Request request MimeHeaders headers byte[] content)

Description copied from interface Filter Filters the content generated by the wrapped Handler The content may be arbitrarily rewritten bythis method

041607Release 23 - 45 -

The MIME headers may also be modified by this Filter for instance to change the Content-Typeof a web page The Content-Length will automatically be computed by the FilterHandler Specified by

filter in interface FilterTags copied from interface Filter Parameters

request - The finished HTTP requestheaders - The MIME headers generated by the Handler content - The output from the Handler that this Filter may rewrite

ReturnsThe rewritten content The Filter may return the original content unchanged The Filtermay return null to indicate that the FilterHandler should stop processing the request andshould not return any content to the client

Description copied from class Template Called before this template processes any tagsOverrides

respond

Release 23041607 - 46 -

tag_forcetimeout

public void tag_forcetimeout (RewriteContext hr)

The ltforcetimeoutgt tag will cause an immediate timeout of the connection to the email server Thistag is mainly intended for debugging

tag_email

public void tag_email (RewriteContext hr)

Handles the ltemailgt tag

tag_folder

public void tag_folder (RewriteContext hr)

Handles the ltfoldergt tag

tag_message

041607Release 23 - 47 -

public void tag_message (RewriteContext hr)

Handles the ltmessagegt tag

tag_sendmail

public void tag_sendmail (RewriteContext hr)

Handles the ltsendmailgt tag

tag_slash_sendmail

public void tag_slash_sendmail (RewriteContext hr)

tag_part

public void tag_part (RewriteContext hr)

Handles the ltpartgt tag

If we run off the end of the page but there is email pending to be sent send it anyway Also check tosee if we have pending message refiles that need to happenOverrides

Release 23041607 - 48 -

Package sunlabsbrazilfilterFilters are a type of handler used by the sunlabsbrazilfilterFilterHandler that canmodify content after it has been obtained by another handler

A filter is a special type of handler that has two additional methods filter and shouldFilter Normally once a handler generates the content for a request the content is delivered to the client and therequest is finished Although this allows for a choice in the manner in which the content is obtained nothing canbe done to modify that content before it is transmitted to the client

The filterHandler arranges for the content generated by another handler (or handlers) to be capturedallowing it to be filtered before it is sent to the client

041607Release 23 - 49 -

Package sunlabsbrazilfilterBrazil project Developer Documentation SML-2006-0530

Class CopyContentFiltersunlabsbrazilfilter Class CopyContentFilter

javalangObject | +-- sunlabsbrazilfilterCopyContentFilter

All Implemented Interfaces Filter Handler

public class CopyContentFilterextends Objectimplements Filter

Filter to save content (of an entire site) to a disk file This is used to steal other sites It is expected to beused in conjunction with a GenericProxyHandler Only files that donrsquot already exist on the local filesystem are saved Properties directoryName

The root in the file system to save the content in

Constructor SummaryCopyContentFilter ()

Method Summary byte[] filter (Request request MimeHeaders headers byte[] content)

Grab the contents and save as a file (if file doesnrsquot already exist)

boolean respond (Request request) This is the request object before the content was fetched

boolean shouldFilter (Request request MimeHeaders headers) Watch every document that passes by

Release 23041607 - 50 -

Brazil project Developer DocumentationClass CopyContentFilter SML-2006-0530

Constructor Detail

CopyContentFilter

public CopyContentFilter ()

Method Detail

respond

public boolean respond (Request request)

This is the request object before the content was fetchedSpecified by

request - The Request object that represents the HTTP request

041607Release 23 - 51 -

Class CopyContentFilterBrazil project Developer Documentation SML-2006-0530

shouldFilter

Watch every document that passes by If the HTTP rerun code is 200 plan to save the content on thelocal file systemSpecified by

filter

Grab the contents and save as a file (if file doesnrsquot already exist) The URL is mapped into a pathnamestarting from directoryName Specified by

ReturnsThe rewritten content The Filter may return the original content unchanged The Filtermay return null to indicate that the FilterHandler should stop processing the request and

Release 23041607 - 52 -

should not return any content to the client

041607Release 23 - 53 -

Class ExecFiltersunlabsbrazilfilter Class ExecFilter

javalangObject | +-- sunlabsbrazilfilterExecFilter

public class ExecFilterextends Objectimplements Filter

Filter to Run all content through an external process filter The content is provided as the standard input to acommand that is expected to return the new content

The following server properties are used command

The command to exec The content is supplied as stdin and the filtered output is expected on stdout$ substitutions Are done at each filter invocation

types A regular expression that matches the content types for the content we wish to filter

type This property is set to the content type of the content just before command is evaluated

newType This property if set is used as the new content type It is evaluated for $ at each conversion

error If the command failed this property will contain the error message If the command generated outputon stderr this property will contain the output

The following configuration will halve the size of all jpeg and gif images using the convert program fromImageMagic

prefixtypes=image(jpeg|gif) prefixcommand= convert -sample 50 $map$prefixtype- $map$prefixtype- mapimagegif=GIF mapimagejpeg=JPEG

Constructor SummaryExecFilter ()

Release 23041607 - 54 -

Brazil project Developer DocumentationClass ExecFilter SML-2006-0530

Run content through filter

boolean shouldFilter (Request request MimeHeaders headers) Only filter content types that match

Constructor Detail

ExecFilter

public ExecFilter ()

Method Detail

server - The HTTP server that created this Handler Typical Handler s will use Serverprops to obtain run-time configuration informationprefix - The handlers name The string this Handler may prepend to all of the keys that it

041607Release 23 - 55 -

Class ExecFilterBrazil project Developer Documentation SML-2006-0530

uses to extract configuration information from Serverprops This is set (by the Server and ChainHandler ) to help avoid configuration parameter namespace collisions

respond

shouldFilter

Only filter content types that matchSpecified by

filter

Release 23041607 - 56 -

Run content through filter Process $Specified by

041607Release 23 - 57 -

Interface Filtersunlabsbrazilfilter Interface Filter All Superinterfaces

HandlerAll Known Implementing Classes

CopyContentFilter EmailTemplate ExecFilter MD5Filter PlainFilter ReFilter ReplaceFilter SessionFilter TemplateFilter UrlMapFilter UrlSessionFilter CookieFilter HistoryFilter TclFilter VelocityFilter

public interface Filterextends Handler

The Filter interface is used by the FilterHandler to examine and dynamically rewrite the contentsof web pages obtained from some source before returning that page to the client

A chain of filters can be established in the manner of a pipeline The FilterHandler sends the output ofa Filter to the input of the next Filter

The init and respond methods inherited from the Handler interface are called as for ordinaryhandlers Handlerinit(sunlabsbrazilserverServer javalangString)

is called when the server starts to obtain run-time configuration information Handlerrespond(sunlabsbrazilserverRequest)

is called when the request comes in before the request is sent to the wrapped handler This methodreturns true to indicate that the request has been completely handled by this Filter and no furtherprocessing filtering takes place

Filters the content generated by the wrapped Handler

Methods inherited from interface sunlabsbrazilserverHandler

init respond

Release 23041607 - 58 -

Brazil project Developer DocumentationInterface Filter SML-2006-0530

Method Detail

shouldFilter

Gives this Filter the chance to examine the HTTP response headers from the wrapped Handler before the content has been retrieved

The MIME headers may also be modified by this Filter for instance to change the Content-Typeof a web page The Content-Length will automatically be computedParameters

filter

Filters the content generated by the wrapped Handler The content may be arbitrarily rewritten bythis method

The MIME headers may also be modified by this Filter for instance to change the Content-Typeof a web page The Content-Length will automatically be computed by the FilterHandler Parameters

041607Release 23 - 59 -

Interface FilterBrazil project Developer Documentation SML-2006-0530

Class FilterHandlersunlabsbrazilfilter Class FilterHandler

javalangObject | +-- sunlabsbrazilfilterFilterHandler

public class FilterHandlerextends Objectimplements Handler

The FilterHandler captures the output of another Handler and allows the ouput to be modified Oneor more Filters may be specified to change that output before it is returned to the client

This handler provides one of the core services now associated with the Brazil Server the ability todynamically rewrite web content obtained from an arbitrary source

For instance the FilterHandler can be used as a proxy for a PDA The wrapped Handler would goto the web to obtain the requested pages on behalf of the PDA Then a Filter would examine alltexthtml pages and rewrite the pages so they fit into the PDArsquos 200 pixel wide screen Another Filterwould examine all requested images and dynamically dither them to reduce the wireless bandwidthconsumed by the PDA

The following configuration parameters are used to initialize this Handler prefix suffix glob match

Specify the URL that triggers this handler (See MatchString ) handler

The name of the Handler whose output will be captured and then filtered This is called thewrapped handler

filters A list of Filter names The filters are applied in the specified order to the output of the wrappedhandler

exitOnError If set the serverrsquos initFailure will set any of the filters fail to initialize No handler prefix isrequired

A sample set of configuration parameters illustrating how to use this handler follows

Release 23041607 - 60 -

Brazil project Developer DocumentationClass FilterHandler SML-2006-0530

handler=filter port=8081

filterclass=sunlabsbrazilfilterFilterHandler filterhandler=proxy filterfilters=noimg

proxyclass=sunlabsbrazilproxyProxyHandler

noimgclass=sunlabsbrazilfilterTemplateFilter noimgtemplate=sunlabsbraziltemplateNoImageTemplate

These parameters set up a proxy server running on port 8081 As with a normal proxy this proxy serverforwards all HTTP requests to the target machine but it then examines all HTML pages before they arereturned to the client and strips out all ltimggt tags By applying different filters the developer couldinstead build a server

to automatically dither embedded images down to grayscale (instead of simply stripping them all out) to apply pattern recognition techniques to strip out only the advertisements to examine and change arbitrary URLs on the page to extract the content from an HTML page and dynamically combine it with another file to produce adifferent look-and-feel

See the description under responnd for a more detailed explaination

Field Summary Filter[] filters

Handler handler

Constructor SummaryFilterHandler ()

Start the handler and filter classes

boolean respond (Request request) Responds to an HTTP request by the forwarding the request to the wrapped Handlerand filtering the output of that Handler before sending the output to the client

041607Release 23 - 61 -

Class FilterHandlerBrazil project Developer Documentation SML-2006-0530

Field Detail

handler

public Handler handler

filters

public Filter[] filters

Constructor Detail

FilterHandler

public FilterHandler ()

Method Detail

Start the handler and filter classesSpecified by

Returnstrue if this Handler initialized successfully false otherwise If false is returned this

Release 23041607 - 62 -

Handler should not be used

respond

Responds to an HTTP request by the forwarding the request to the wrapped Handler and filtering theoutput of that Handler before sending the output to the client

At several stages the Filters are given a chance to short-circuit this process 1 Each Filter is given a chance to examine the request before it is sent to the Handler by

invoking its respond() method The Filter may decide to change the requestrsquos properties A Filter may even return some content to the client now by (calling requestsendResponse() and returning true) in which case neither the Handler norany further Filter s are invoked at all

2 Assuming the respond() methods of all the filters returned false (which is normally the case) the handlerrsquos respond() method is called and is expected to generate content If no content isgenerated at this step this handler returns false

3 After the Handler has generated the response headers but before it has generated any contenteach Filter is asked if it would be interested in filtering the content If no Filter is then thesubsequent content from the Handler will be sent directly to the client

4 On the other hand if any Filter is interested in filtering the content then the output of the Handler will be sent to each of the interested Filter s in order The output of each interested Filter is sent to the next one the output of the final Filter is sent to the client

5 At this point any one of the invoked Filter s can decide to reject the content completelyinstead of rewriting it

See Filter for a description of how to cause filters to implement the various behaviors defined aboveSpecified by

respond in interface HandlerParameters

request - The HTTP request to be forwarded to one of the sub-serversReturns

true if the request was handled and content was generated false otherwiseThrows

IOException - if there was an IO error while sending the response to the client

041607Release 23 - 63 -

Class MD5Filtersunlabsbrazilfilter Class MD5Filter

javalangObject | +-- sunlabsbrazilfilterMD5Filter

public class MD5Filterextends Objectimplements Filter

Filter to compute the MD5 checksum of the content and generate the appropriate Content-MD5 httpheader As md5 checksum generation can be expensive care should be taken as to which types of contentare digested

The following server properties are used prefix suffix glob match

Specify the URLs that trigger this filter (See sunlabsbrazilhandlerMatchString )

Constructor SummaryMD5Filter ()

Compute digest add to header

boolean init (Server server String prefix) Make sure MD5 is available in this VM or donrsquot start

boolean shouldFilter (Request request MimeHeaders headers) Only filter urlrsquos that match

Release 23041607 - 64 -

Brazil project Developer DocumentationClass MD5Filter SML-2006-0530

Constructor Detail

MD5Filter

public MD5Filter ()

Method Detail

Make sure MD5 is available in this VM or donrsquot startSpecified by

respond

041607Release 23 - 65 -

Class MD5FilterBrazil project Developer Documentation SML-2006-0530

shouldFilter

Only filter urlrsquos that matchSpecified by

filter

Compute digest add to headerSpecified by

Release 23041607 - 66 -

Class PlainFiltersunlabsbrazilfilter Class PlainFilter

javalangObject | +-- sunlabsbrazilfilterPlainFilter

public class PlainFilterextends Objectimplements Filter

Filter to turn textplain into html This allows plain text to be processed by other filters that only deal withhtml

The following server properties are used template

The string to use as an html template The string should contain a single which is replaced by thetextplain content The default stuff the content between ltpregtltpregt

Constructor SummaryPlainFilter ()

Wrap html around textplain converting it to html

boolean shouldFilter (Request request MimeHeaders headers) Only filter textplain documents

041607Release 23 - 67 -

Class PlainFilterBrazil project Developer Documentation SML-2006-0530

Constructor Detail

PlainFilter

public PlainFilter ()

Method Detail

respond

Release 23041607 - 68 -

Brazil project Developer DocumentationClass PlainFilter SML-2006-0530

shouldFilter

Only filter textplain documentsSpecified by

filter

Wrap html around textplain converting it to html Change the content-type to texthtmlSpecified by

041607Release 23 - 69 -

Class ReFiltersunlabsbrazilfilter Class ReFilter

javalangObject | +-- sunlabsbrazilfilterReFilter

public class ReFilterextends Objectimplements Filter

Filter to replace text content via a reqular expression substitution See Regexpsub(javalangString javalangString) and RegexpsubAll(javalangString javalangString)

Note The regular expression processing should be consolodated with the RePollHandler and thetag_extract processing

The following server properties are used re

The regular expression to match the content sub

The replacement expression If not specified the matched content is deleted oneOnly

If set only replace the first match by default all matches are replaced noCase

If set case-insensitive matchins is performed

Constructor SummaryReFilter ()

Release 23041607 - 70 -

Brazil project Developer DocumentationClass ReFilter SML-2006-0530

If the content matches the regular expression do the substitution

boolean shouldFilter (Request request MimeHeaders headers) Only filter text documents

Constructor Detail

ReFilter

public ReFilter ()

Method Detail

041607Release 23 - 71 -

Class ReFilterBrazil project Developer Documentation SML-2006-0530

respond

shouldFilter

Only filter text documentsSpecified by

filter

Release 23041607 - 72 -

If the content matches the regular expression do the substitution Otherwise return the original content un-changedSpecified by

041607Release 23 - 73 -

Class ReplaceFiltersunlabsbrazilfilter Class ReplaceFilter

javalangObject | +-- sunlabsbrazilfilterReplaceFilter

public class ReplaceFilterextends Objectimplements Filter

Filter to replace current content with a static form or template This should be called the TemplateFilterbut that namersquos already taken The content is replaced by the template lock-stock-and-barrel Typically anupstream filter has extracted the relevent parts of the content and a down-stream filter will combine it withthe template The filename to use for the template is computed at each request so it may be modifieddynamically The following server properties are used type

Text subtype of content to filter Defaults to html debug

If set the template is re-read each time Otherwise a cached copy is used fileName

Name of the file to use as the form or template The file is searched for as a Resource if not found inthe filesystem

root The document root used to find the template file If not found root with no prefix is used instead

Constructor SummaryReplaceFilter ()

Release 23041607 - 74 -

Brazil project Developer DocumentationClass ReplaceFilter SML-2006-0530

Grab the template file name Read in the file and deliver it as content

boolean shouldFilter (Request request MimeHeaders headers) Only replace text documents

Constructor Detail

ReplaceFilter

public ReplaceFilter ()

Method Detail

041607Release 23 - 75 -

Class ReplaceFilterBrazil project Developer Documentation SML-2006-0530

respond

shouldFilter

Only replace text documentsSpecified by

filter

Release 23041607 - 76 -

Grab the template file name Read in the file and deliver it as contentSpecified by

041607Release 23 - 77 -

Class SessionFiltersunlabsbrazilfilter Class SessionFilter

javalangObject | +-- sunlabsbrazilfilterSessionFilter

public class SessionFilterextends Objectimplements Filter

Filter to manage browser sessions using browser cookies or URL rewriting as needed This should be usedas the last filter in the filter chain It attempts to use browser cookies If they donrsquot work it rewrites theURLrsquos instead tacking the session info onto the end of the URL

This Filter works by first examining the request as a handler If the request contains an ID either in thebrowser cookie or written into the URL the session ID is extracted In the id-in-the-url case the ID isremoved from the URL When called later as a filter the SessionFilter rewrites all relevent URLrsquos in thepage to incorporate the ID

If an ID canrsquot be found either in the cookie or URL a couple the session creation sequence starts First thebrowser is send a set-cookie request along with a redirect that contains the cookie value encoded into theredirected URL When the browser follows the redirect the request is examined to se if the cookie valuewas sent If so the browser is redirected back to the original URL and normal cookie processing takesplace If no cookie is found the browser is redirected back to the original URL modified to embed the IDinto it and normal URL session rewriting takes place

The following server properties are used cookie

The name of the cookie to use (defaults to cookie) If the name is none then no cookies are usedInstead session rewriting will occur for every session

session The name of the request property that the Session ID will be stored in to be passed to downstreamhandler The default value is SessionID If the session property is set and not empty then noprocessing is done

persist If set cookies persist across browser sessions If cookies are disabled no persistence is available

cookiePrefixThe URL prefix for which the cookie applies Defaults to

suffix A regular expression that matches url suffix we process Defaults to html|xml|txt

The Following request properties are set

Release 23041607 - 78 -

Brazil project Developer DocumentationClass SessionFilter SML-2006-0530

gotCookie An id was retrieved out of a cookie header

UrlID Set to the string tacked onto the end of each URL if session IDrsquos are managed by URL rewriting Ifcookies are used this is set to the empty string

Field Summary String cookieName

String encoding

boolean persist

String redirectToken

String session

String urlSep

Constructor SummarySessionFilter ()

Rewrite all the urlrsquos adding the session id to the end

boolean init (Server server String propsPrefix) Initializes the handler

boolean respond (Request request) This is called by the filterHandler before the content generation step

boolean shouldFilter (Request request MimeHeaders headers) We have the results only filter if html and wersquore rewriting

041607Release 23 - 79 -

Class SessionFilterBrazil project Developer Documentation SML-2006-0530

Field Detail

session

public String session

cookieName

public String cookieName

urlSep

public String urlSep

redirectToken

public String redirectToken

encoding

public String encoding

persist

public boolean persist

Constructor Detail

SessionFilter

public SessionFilter ()

Method Detail

Release 23041607 - 80 -

public boolean init (Server server String propsPrefix)

respond

This is called by the filterHandler before the content generation step It is responsible for extracting thesession information then (if required) restoring the URLrsquos to their original form It tries relatively hardto use cookies if they are available through a series or redirectsSpecified by

041607Release 23 - 81 -

shouldFilter

We have the results only filter if html and wersquore rewritingSpecified by

filter

Rewrite all the urlrsquos adding the session id to the endSpecified by

Release 23041607 - 82 -

Class TemplateFiltersunlabsbrazilfilter Class TemplateFilter

javalangObject | +-- sunlabsbrazilfilterTemplateFilter

public class TemplateFilterextends Objectimplements Filter

The TemplateFilter sends HTML content through an HtmlXML parser to a set of Template s EachHtmlXML tag may dynamically invoke a Java method present in the Template s Thedynamically-generated content from evaluating the HtmlXML tags is returned to the caller

The following configuration parameters are used to initialize this Filter templates

A list of template names For each name in the list the property nameclass is examined todetermine which class to use for each template Then name is used as the prefix for other templatespecific properties if any If nameclass does not exist then name is assumed to be the class nameand there are no template specific properties for the template Methods in the template classes will beinvoked to process the XMLHTML tags present in the content

session The request property that contains the session ID If no session property is found with the suppliedprefix then the global session property is used instead The default value is SessionID

subtype Restrict this template to only handle specified text sub-types defaults to the empty string whichimplies any text sub-type

encoding The charset encoding to use to represent the content as text If none is specified the default encoding isused

outputEncoding The character encoding to use to interpret the template results If no outputEncoding is specifiedthen encoding is used Once template processing is complete the results are converted into a bytestream for transmission to the next filter using outputEncoding if specified If not specified then thedefault encoding is used

tagPrefix If specified all tag names defined for each template class are prefixed with tagPrefix This parameteronly takes effect if the tagPrefix option is not specified for an individual template

The TemplateHandler class is similar but not identical to running a FilterHandler with the FileHandler and the TemplateFilter The differences between the two should be resolved

041607Release 23 - 83 -

Class TemplateFilterBrazil project Developer Documentation SML-2006-0530

Note The templates property accepts a list of class names or tokens that could be used to represent classnames If class names are used all template classes share the TemplateHandlerrsquos properties prefix

Constructor SummaryTemplateFilter ()

Evaluates the content as htmlXML tags if the file is (or has now been converted to) texthtml

boolean respond (Request request) No action before request is made

boolean shouldFilter (Request request MimeHeaders headers) Filters all HTML files or files that are likely to be html files specifically those whoseContent-Type starts with text

Constructor Detail

TemplateFilter

public TemplateFilter ()

Method Detail

Release 23041607 - 84 -

Brazil project Developer DocumentationClass TemplateFilter SML-2006-0530

respond

No action before request is madeSpecified by

shouldFilter

Filters all HTML files or files that are likely to be html files specifically those whose Content-Type

041607Release 23 - 85 -

starts with textSpecified by

filter

Evaluates the content as htmlXML tags if the file is (or has now been converted to) texthtmlSpecified by

Release 23041607 - 86 -

Class UrlMapFiltersunlabsbrazilfilter Class UrlMapFilter

javalangObject | +-- sunlabsbrazilfilterUrlMapFilter

public class UrlMapFilterextends Objectimplements Filter

Filter to Map urlrsquos from any proxied content The MultiProxyHandler is used to virtually mount otherweb sites into the local document root In the process it rewrites all the local urlrsquos found in the proxiedcontent to point to the locally mounted version

This filter examimes content derived from non-proxied sources for absolute urlrsquos to proxied sites andrewrites them to point to the virtual mount point on the local machine instead of directly to the mountedsite

Constructor SummaryUrlMapFilter ()

Rewrite all absolute links if there are any left

boolean shouldFilter (Request request MimeHeaders headers) Only filter text documents if the MultiProxyHandler was called

041607Release 23 - 87 -

Class UrlMapFilterBrazil project Developer Documentation SML-2006-0530

Constructor Detail

UrlMapFilter

public UrlMapFilter ()

Method Detail

respond

Release 23041607 - 88 -

Brazil project Developer DocumentationClass UrlMapFilter SML-2006-0530

shouldFilter

Only filter text documents if the MultiProxyHandler was calledSpecified by

filter

Rewrite all absolute links if there are any leftSpecified by

041607Release 23 - 89 -

Class UrlSessionFiltersunlabsbrazilfilter Class UrlSessionFilter

javalangObject | +-- sunlabsbrazilfilterUrlSessionFilter

public class UrlSessionFilterextends Objectimplements Filter

Sample filter to use urlrsquos instead of cookies for sessions When html files are delivered all URLrsquos back tothis host are changed to add in the session information When requests are made the session info is strippedoff the URL which is passed to the rest of the handlers

Note This fiter has been superceded by the SessionFilter It is included for illustrative purposes only

Field Summary String session

Constructor SummaryUrlSessionFilter ()

Release 23041607 - 90 -

Brazil project Developer DocumentationClass UrlSessionFilter SML-2006-0530

boolean respond (Request request) Extract the cookie out of the URL rewriting the url as needed

boolean shouldFilter (Request request MimeHeaders headers) We have the results only filter if html

Field Detail

session

Constructor Detail

UrlSessionFilter

public UrlSessionFilter ()

Method Detail

Description copied from interface Handler Initializes the handler

041607Release 23 - 91 -

Class UrlSessionFilterBrazil project Developer Documentation SML-2006-0530

Specified by init in interface Handler

Tags copied from interface Handler Parameters

respond

Extract the cookie out of the URL rewriting the url as needed Add the session info at the end of theurl abhtml -gt abhtml$xxxx where xxx is the session This gets called before the original request is madeSpecified by

shouldFilter

We have the results only filter if htmlSpecified by

shouldFilter in interface Filter

Release 23041607 - 92 -

Tags copied from interface Filter Parameters

filter

041607Release 23 - 93 -

Package sunlabsbrazilgroovyProvide ways of integrating the Groovy scripting language into the Brazil project server

See groovycodehausorg for more information about Groovy Files in this package require groovyjaras well as other jar s that are part of the Groovy system This package has been tested using a commandline like

java -classpath braziljargroovy-all-10-jsr-04jar

Release 23041607 - 94 -

Brazil project Developer DocumentationPackage sunlabsbrazilgroovy SML-2006-0530

Class GroovyServerTemplatesunlabsbrazilgroovy Class GroovyServerTemplate

javalangObject | +--sunlabsbraziltemplateTemplate | +-- sunlabsbrazilgroovyGroovyServerTemplate

public class GroovyServerTemplateextends Template

The GroovyServerTemplate looks for each ltgroovygt tag in an HTML page and treats thefollowing data up to the next ltgroovygt ) tag as a groovy script to evaluate

All Groovy fragments within a given page are evaluated in the same Groovy interpreter The Groovyinterpreter actually lives for the entire duration of this Template object so the user can implementpersistence across requests Each session gets its own interpreter

The name of the Groovy script to evaluate when the interpreter is created This script only evaluatedwhen the interp is created not on every request The variables prefix and server are set beforethis file is evaluated and are references to the parameters passed to a handler init method

debug If this configuration parameter is present this class replaces the ltgroovygt and ltgroovygt tagswith comments so the user can keep track of where the dynamically generated content is coming fromby examining the comments in the resultant HTML document By default the ltgroovygt and ltgroovygt are completely eliminated from the HTML document rather than changed intocomments

Before evaluating each HTML document this class sets variables in the Groovy interpreter which can beused to interact back with Java to do things like set the response headers request

Exposes the handler prefix String

041607Release 23 - 95 -

Class GroovyServerTemplateBrazil project Developer Documentation SML-2006-0530

server Exposes the handler Server object

Constructor SummaryGroovyServerTemplate ()

Initialize the groovy interperter (1st time only) and set the current request object

void tag_groovy (RewriteContext hr)

Constructor Detail

GroovyServerTemplate

Release 23041607 - 96 -

Brazil project Developer DocumentationClass GroovyServerTemplate SML-2006-0530

public GroovyServerTemplate ()

Method Detail

Initialize the groovy interperter (1st time only) and set the current request objectOverrides

tag_groovy

public void tag_groovy (RewriteContext hr)

041607Release 23 - 97 -

Package sunlabsbrazilhandlerThis package contains a collection classes that implement the sunlabsbrazilserverHandlerinterface for use with the sunlabsbrazilserverServer package along with several supportclasses

Just about the only thing they have in common is their lack of dependencies on any other packages Someprovide generic capabilities such as standard CGI interfaces or template processing others are either specialpurpose provided to demonstrate how to write handlers and others are skeleton handlers designed to be finished to provide application specific functionality

You can find a summary of the handlersrsquo options here

Release 23041607 - 98 -

Brazil project Developer DocumentationPackage sunlabsbrazilhandler SML-2006-0530

Class AclSwitchHandlersunlabsbrazilhandler Class AclSwitchHandler

javalangObject | +-- sunlabsbrazilhandlerAclSwitchHandler

public class AclSwitchHandlerextends Objectimplements Handler

Simple access control hander based on url prefixes or regexps Looks up list of valid prefixes or regularexpressions in Requestprops and allowsdenies access based on those prefixes This is expected towork in conjunction with an upstream handler such as RolesHandler or BasicAuthHandler thatexamines the request and place credentials into the request object The credentials consist of url prefixes orregular expressions that match classes of urlrsquos Documents whose URL prefix donrsquot match a credential arerejected If a credential does not begin with a slash () the init(sunlabsbrazilserverServer javalangString) prefix for this handler isprepended

Properties prefix suffix glob match

Sepcify the URL that triggers this handler (See MatchString ) authName

The name of the requestprops entry to find a white-space delimited list of url prefixes or regularexpression patterns (defaults to roles) If the items in the list donrsquot start with then the url prefixis prepended (only for prefix matching)

redirect Name of the url to re-direct to if permission is denied If not specified a simple message is sent to theclient

useRegexpIf provided the list of credentials is interpreted as regular expressions otherwise url prefixes are used

Constructor SummaryAclSwitchHandler ()

041607Release 23 - 99 -

Class AclSwitchHandlerBrazil project Developer Documentation SML-2006-0530

Constructor Detail

AclSwitchHandler

public AclSwitchHandler ()

Method Detail

Release 23041607 - 100 -

Brazil project Developer DocumentationClass AclSwitchHandler SML-2006-0530

respond

041607Release 23 - 101 -

Class BasicAuthHandlersunlabsbrazilhandler Class BasicAuthHandler

javalangObject | +-- sunlabsbrazilhandlerBasicAuthHandler

public class BasicAuthHandlerextends Objectimplements Handler

The BasicAuthHandler obtains a Session ID by performing basic authentication using either theAuthorization or the Proxy-Authorization headers This handler prevents subsequent downstreamhandlers from being accessed unless the proper authentication was seen in the request The Session IDobtained by this handler is meant to be used by those downsteams handlers to access whateversession-dependent information they need

If the request does not contain the authentication headers or the authentication information is not valid thishandler sends an HTTP error message along with the WWW-Authenticate or Proxy-Authenticateheader as appropriate See code [p ] authorization [p ] authenticate [p ]

If the request does contain valid authentication information the Session ID associated with theauthentication information is inserted into the request properties for use by downstream handlers Afterinserting the Session ID this handler returns false to allow the downstream handlers to run IF theSession ID in empty (eg ) then although authenticateion succeeds no Session Id property is set

The set of valid Session IDs is contained in a globally accessible table managed by the SessionManager which may be initialized with a static table (see mapFile [p ] )

The format of the initialization table (if any) described above is a Java properties file where keys are theBase64 encoded strings obtained from the Authentication header and the values are the associated SessionIDs Base64 strings can contain the rsquo=rsquo character but the keys in a Java properties file cannot contain an rsquo=rsquocharacter so all rsquo=rsquo characters in the Base64 strings must be converted to rsquorsquo in the properties file as shownin the following sample properties file

bXIuIGhhdGU6a2ZqYw = radion Zm9vOmJhcg = foo

The data in the SessionManager table doesnrsquot use the rsquorsquos only =rsquos

There are several different types of authentication possible All authentication handlers should follow thesebasic principles

The authentication handler examines some aspect of the request to decide if the appropriate

Release 23041607 - 102 -

Brazil project Developer DocumentationClass BasicAuthHandler SML-2006-0530

authentication is present If the request is acceptable the authentication handler should insert the extracted Session ID into arequest property and then return false to allow subsequent handlers to run and perhaps use theSession ID If the request is not acceptable the authentication handler can return an error message or do someother thing to try to obtain a valid authentication Handlers wishing to be protected by authentication should not subclass an authentication handlerInstead such handler should be written to assume that authentication has already been performed and then justexamine the Session ID present The web developer is then responsible for choosing which one (of possiblymany) forms of authentication to use and installing those authentication handlers before the sensitive handler Handlers that are protected by an authentication handler can use the Session ID stored in the requestproperties regardless of the specifics of the authentication handler

handlers=auth history file

authclass=BasicAuthHandler authsession=account authmessage=Go away yoursquore not allowed here

historyclass=HistoryHandler historysession=account

fileclass=FileHandler fileroot=htdocs

In the sample pseudo-configuation file specified above the BasicAuthHandler is first invoked to see ifthe HTTP basic authentication header is present in the request If it isnrsquot a nasty message is sent back Ifthe basic authentication header is present and corresponds to a user that the BasicAuthHandlerknows about the Session ID associated with that user is stored in the specified property named account

Subsequently the HistoryHandler examines its specified property (also account) for the Session IDand uses that to keep track of which session is issuing the HTTP request

Each handler that needs a Session ID should have a configuration parameter that allows the web developerto specify the name of the request property that holds the Session ID Multiple handlers can all use the samerequest property as each other all protected by the same authentication handler

This handler uses the following configuration properties prefix suffix glob match

Sepcify the URL that triggers this handler code

The type of authentication to perform The default value is 401

The value 401 corresponds to standard basic authentication The Authorization request header issupposed to contain the authentication string If the request was not authenticated theWWW-Authenticate header is sent in the HTTP error response to cause the browser to prompt theclient to authenticate

041607Release 23 - 103 -

Class BasicAuthHandlerBrazil project Developer Documentation SML-2006-0530

The value 407 corresponds to basic proxyfirewall authentication The Proxy-Authorizationrequest header is supposed to contain the authentication string If the request was not authenticated theProxy-Authenticate header is sent in the HTTP error response to cause the browser to prompt the client toauthenticate

Any other value may also be specified Whatever the value it will be returned as the HTTP result codeof the error message

authorization If specified this is the request header that will contain the basic authentication string instead of theAuthorization or Proxy-Authorization header implied by code

authenticate If specified this is the response header that will be sent in the HTTP error response if the user is notauthenticated

If this string is then this handler will authenticate the request if the authorization header is presentbut will not send an HTTP error message if the request could not be authenticated This is useful if theweb developer wants to do something more complex (such as invoking an arbitrary set of handlers)instead of just sending a simple error message if the request was not authenticated In this case theweb developer can determine that the request was not authenticated because no Session ID will bepresent in the request properties

realm The realm of the HTTP authentication error message This is a string that the browser is supposed topresent to the client when asking the client the authenticate It provides a human-friendly namedescribing who wants the authentication

message The body of the HTTP authentication error message This will be displayed by the browser if the clientchooses not to authenticate The default value is Patterns of the form $xxx are replaced with thevalue of the xxx entry of requestprops

mapFile If specified this is the initial Session ID file This is expected to be a java properties file whose keysare the authentication tokens and whose values are the Session IDs that are inserted into the requestproperties

The keys in the file are basic authentication (base64) tokens with any trailing = characters changedto

session The name of the request property that the Session ID will be stored in to be passed to downstreamhandlers The default value is SessionID

ident The ident argument to SessionManagergetSession(javalangObjectjavalangObject javalangClass) to get the table of valid sessions The default valueis authorized If ident is of the form identsession then the session portion is used as the session argument to SessionManagerget() Otherwise the session argument is NULL This tablemay be manipulated with the SetTemplate using the ident namespace and session for theSetTemplate sessionTable parameter

Release 23041607 - 104 -

Field Summary String authenticate

String authorization

int code

String ident

String mapFile

String message

String realm

String session

String sessionTable

Constructor SummaryBasicAuthHandler ()

Method Summary boolean complain (Request request String reason)

Authentication failed

boolean init (Server server String propsPrefix) Initializes this handler

boolean respond (Request request) Looks up the credentials for this request and insert them into the request stream

041607Release 23 - 105 -

Field Detail

public int code

authorization

public String authorization

authenticate

public String authenticate

public String realm

message

public String message

mapFile

public String mapFile

session

Release 23041607 - 106 -

public String ident

sessionTable

public String sessionTable

Constructor Detail

BasicAuthHandler

public BasicAuthHandler ()

Method Detail

Initializes this handler It is an error if the mapFile parameter is specified but that file cannot be loadedSpecified by

init in interface HandlerParameters

server - The HTTP server that created this handlerprefix - A prefix to prepend to all of the keys that this handler uses to extract configuration information

Returnstrue if this Handler initialized successfully false otherwise

respond

Looks up the credentials for this request and insert them into the request stream If no credentials arefound prompt the user for themSpecified by

041607Release 23 - 107 -

complain

public boolean complain (Request request String reason) throws IOException

Authentication failed Send the appropriate authentication required header as a responseParameters

request - The request to respond toreason - The reason for failure (for diagnostics)

ReturnsTrue

Release 23041607 - 108 -

Class CgiHandlersunlabsbrazilhandler Class CgiHandler

javalangObject | +-- sunlabsbrazilhandlerCgiHandler

public class CgiHandlerextends Objectimplements Handler

Handler for implementing cgi11 interface This implementation allows either suffix matching (eg cgi) toidentify cgi scripts or prefix matching (eg bgi-bin) Defaults to All output from the cgi script isbuffered (eg chunked encoding is not supported) NOTE in versions of Java prior to release 13 the ability to set a working directory when running anexternal process is missing This handler automatically checks for this ability and sets the proper workingdirectory but only if the underlying VM supports it

The following request properties are used root

The document root for cgi files suffix

The suffix for cgi files (defaults to cgi) prefix

The prefix for all cgi files (eg cgi-bin) url

o(riginal) or c(urrent) If an upstream handler has changed the URL this specifes which url to lookfor the cgi script relative to The default is to use the original url

custom set to true to enable custom environment variables If set all server properties starting with thishandlerrsquos prefix are placed into the environment with the name CONFIG_name where name is theproperty key in upper case with the prefix removed This allows cgi scripts to be customized in theserverrsquos configuration file

runwith The command to use to run scripts The absolute file path is added as the last parameter If notspecified the file name is run as the command

noheadersAccording to the CGI spec cgi documents are to begin with properly formed http headers to specifiethe type return status and optionally other meta information about the request if noheaders isspecified then the content is expected to not have any http headers and the content type is asimplied by the url suffix

See example configuration in the samples included with the distribution

041607Release 23 - 109 -

Class CgiHandlerBrazil project Developer Documentation SML-2006-0530

Constructor SummaryCgiHandler ()

One time initialization

boolean respond (Request request) Dispatch and handle the CGI request

Constructor Detail

CgiHandler

public CgiHandler ()

Method Detail

One time initialization The handler configuration properties are extracted and set in respond(Request) to allow upstream handlers to modify the parametersSpecified by

Release 23041607 - 110 -

Brazil project Developer DocumentationClass CgiHandler SML-2006-0530

prefix - The handlers name The string this Handler may prepend to all of the keys that ituses to extract configuration information from Serverprops This is set (by the Server and ChainHandler ) to help avoid configuration parameter namespace collisions

respond

Dispatch and handle the CGI request Gets called on ALL requests Set up the environment exec theprocess and deal appropriately with the input and output In this implementation all cgi script filesmust end with a standard suffix although the suffix may omitted from the url The urlmaindometooa=b will look starting in DocRoot for maincgi maindocgi etc until a matchingfile is found

Input parameters examined in the request properties Suffix

The suffix for all cgi scripts (defaults to cgi) DocRoot

The document root for locating the script Specified by

041607Release 23 - 111 -

Class ChainSawHandlersunlabsbrazilhandler Class ChainSawHandler

javalangObject | +--sunlabsbrazilserverChainHandler | +-- sunlabsbrazilhandlerChainSawHandler

public class ChainSawHandlerextends ChainHandler

Variant of the chain handler for doing standard logging Donrsquot use on fine furniture

Output is a variant of the common logfile format The common logfile format is as follows

remotehost rfc931 authuser [date] request status bytes

remotehost Remote hostname (or IP number if DNS hostname is not available or if DNSLookup is Off

rfc931 The remote logname of the user

authuser The username as which the user has authenticated himself

[date] Date and time of the request

request The request line exactly as it came from the client

status The HTTP status code returned to the client

bytes The content-length of the document transferred

referrer (optional) the referring url

user agent (optional) The user agent making the request

Additional Configuration options logFile

The name of the file to write the logs to flush

The number of requests between flushes to the file If the logFile is removed the server creates a new one Thus logs may be truncated by periodically movingthem to another name (at least on unix)

Release 23041607 - 112 -

Brazil project Developer DocumentationClass ChainSawHandler SML-2006-0530

See the LogHandler handler for generating logs whose contents are configurable

Field Summarystatic int BUFSIZE

static String FLUSH

static String LOG

Fields inherited from class sunlabsbrazilserverChainHandler

exitOnError handlers isMine names prefix report

Constructor SummaryChainSawHandler ()

Initializes this ChainHandler by initializing all the wrapped handlers in the list of handlers

boolean respond (Request request) Run the chain-handler counting the of bytes of output generated by its chained handlers

Methods inherited from class sunlabsbrazilserverChainHandler

initHandler

041607Release 23 - 113 -

Class ChainSawHandlerBrazil project Developer Documentation SML-2006-0530

Field Detail

public static final String LOG

public static final String FLUSH

BUFSIZE

public static final int BUFSIZE

Constructor Detail

ChainSawHandler

public ChainSawHandler ()

Method Detail

Description copied from class ChainHandler Initializes this ChainHandler by initializing all the wrapped handlers in the list of handlers If awrapped handler cannot be initialized this method logs a message and skips it If no handlers werespecified or no handlers were successfully initialized then the initialization of this ChainHandleris considered to have failedOverrides

init in class ChainHandlerTags copied from class ChainHandler

Release 23041607 - 114 -

Parametersserver - The HTTP server that created this ChainHandler prefix - The prefix for this ChainHandler rsquos properties

Returnstrue if at least one of the wrapped handlers was successfully initialized

respond

Run the chain-handler counting the of bytes of output generated by its chained handlersOverrides

respond in class ChainHandlerTags copied from class ChainHandler Parameters

request - The HTTP requestReturns

true if one of the Handler s returns true false otherwiseThrows

IOException - if one of the Handler s throws an IOException while responding

041607Release 23 - 115 -

Class ChownHandlersunlabsbrazilhandler Class ChownHandler

javalangObject | +-- sunlabsbrazilhandlerChownHandler

public class ChownHandlerextends Objectimplements Handler

Handler for changing the group and owner of the server This handler expects the serverso file used bythe Java Webserver 20 Make sure you rename the file libserverso in the distribution to libcom_sun_server_ServerProcessso and put it where it will be found by SystemloadLibrary Note If the native library is unalvailable on your platform try the RunAs handler that includes the nativesource code

Properties userName

name of the user to run as groupName

The name of the group to run as

Constructor SummaryChownHandler ()

set up the Unix user and group

boolean respond (Request request) Nothing to respond to

Release 23041607 - 116 -

Brazil project Developer DocumentationClass ChownHandler SML-2006-0530

Constructor Detail

ChownHandler

public ChownHandler ()

Method Detail

set up the Unix user and group We could return false so our respond method would never be calledbut some containers cause the server to exit on false returnsSpecified by

respond

Nothing to respond toSpecified by

041607Release 23 - 117 -

Class ChownHandlerBrazil project Developer Documentation SML-2006-0530

Release 23041607 - 118 -

Class ConfigFileHandlersunlabsbrazilhandler Class ConfigFileHandler

javalangObject | +-- sunlabsbrazilhandlerConfigFileHandler

public class ConfigFileHandlerextends Objectimplements Handler

Handler for manipulating per-user session state that can be represented as ASCII namevalue pairs Thestate for each session is stored in a file which is expected to be in java properties format If prefix ismatched the contents of the (usually cached) config file for the current session is added to the requestproperties If the url matches the set property the contents of the config file are changed based on thesupplied query parameters (either GET of POST) If no config file exists for the session one is created froma default properties file Only properties already in the config file may be changed using the set method Ifa is specified in the file name it is replaced by the SessionID property if any or common if sessionsarenrsquot used This should be replaced with something more general so we can have more arbitrary mappingsbetween request and the session info

The following request properties are used prefix

The URL prefix required for all documents set

The url pattern to match setting properties Currently it must also match prefix noContent

a url matching the set pattern that causes a 204 no content to be returned to the client(experimental)

name The name of the config file the first is replaced by the current SessionID

default The default properties file to seed session properties

glob Properties that match this glob pattern may be set using the set pattern If this property is specifiedthe default property is optional

root The document root (no properties prefix required) If the name or default properties donrsquot startwith a this is used as the current directory

If is specified in the file name a new session file is created only if 1) a property is changed from thedefault and 2) A cookie was received by the browser

041607Release 23 - 119 -

Class ConfigFileHandlerBrazil project Developer Documentation SML-2006-0530

See also SetTemplate which is preferrable in most cases providing a templated based (instead of URLbased) mechanism for maintaining persistent properties

Constructor SummaryConfigFileHandler ()

Make sure default properties exist before starting this handler or that match is specified

boolean respond (Request request) Extract the session state into the request object optionally modifying the properties

Constructor Detail

ConfigFileHandler

public ConfigFileHandler ()

Method Detail

Make sure default properties exist before starting this handler or that match is specifiedSpecified by

init in interface HandlerTags copied from interface Handler

Release 23041607 - 120 -

Brazil project Developer DocumentationClass ConfigFileHandler SML-2006-0530

Parametersserver - The HTTP server that created this Handler Typical Handler s will use Serverprops to obtain run-time configuration informationprefix - The handlers name The string this Handler may prepend to all of the keys that ituses to extract configuration information from Serverprops This is set (by the Server and ChainHandler ) to help avoid configuration parameter namespace collisions

respond

Extract the session state into the request object optionally modifying the properties If the propertiesare modified they are stored in a file for safe keepingSpecified by

041607Release 23 - 121 -

Class CookieSessionHandlersunlabsbrazilhandler Class CookieSessionHandler

javalangObject | +-- sunlabsbrazilhandlerCookieSessionHandler

public class CookieSessionHandlerextends Objectimplements Handler

Handler for creating browser sessions using cookies This handler provides a single cookie-id that may beused by other handlers The intent is to require only one cookie per server (See also SessionFilter which manages sessions with or without cookies) The following server properties are used prefix suffix glob match

Specify the URL that triggers this handler (See MatchString )

If prefix is specified it is also used to instruct the client to limit the scope of the browser cookie tothat prefix

cookie the name of the cookie to use (defaults to cookie)

map If specified the ident argument to SessionManagergetSession(javalangObjectjavalangObject javalangClass) to get the table of valid cookies used to map thecookie value to a Session ID By default the Session ID stored in the request is the cookie value itself

exist If specified this means that the Session ID corresponding to the cookie value must already exist in the SessionManager Normally if the cookie was not present a new cookie is automatically created

persist If set cookies persist across browser sessions

session The name of the request property that the Session ID will be stored in to be passed to downstreamhandler The default value is SessionID If the property already exists and is not empty no actionwill be taken

If a cookie was returned from the browser the property gotCookie is set to the cookie name Otherwiseit is left unset

Release 23041607 - 122 -

Brazil project Developer DocumentationClass CookieSessionHandler SML-2006-0530

String ident

boolean mustExist

boolean persist

String session

Constructor SummaryCookieSessionHandler ()

Method Summary boolean init (Server server String propsPrefix)

Field Detail

cookieName

041607Release 23 - 123 -

Class CookieSessionHandlerBrazil project Developer Documentation SML-2006-0530

public String ident

mustExist

public boolean mustExist

persist

session

Constructor Detail

CookieSessionHandler

public CookieSessionHandler ()

Method Detail

Release 23041607 - 124 -

respond

041607Release 23 - 125 -

Class DefaultFileHandlersunlabsbrazilhandler Class DefaultFileHandler

javalangObject | +-- sunlabsbrazilhandlerDefaultFileHandler

public class DefaultFileHandlerextends Objectimplements Handler

Handler for appending a url ending with rsquorsquo into the appropriate url based on a default file in the file system

The following request properties are used defaults

The names of the default files to search for in the directory implied by the URL The first one thatexists will cause its name to be appended to the URL Defaults to indexhtml

rootThe document root to look for files If none is found with our prefix then root is examined Defaultsto

DirectoryNameThis property is set if the URL represents a valid directory in the document root

fileNameThis property is set to the name of the default file if one was found

If a url ends with but is a readable plain file the is removed

Constructor SummaryDefaultFileHandler ()

Remember our prefix in the properties table

boolean respond (Request request) If the url ends with a look around in the corrosponding directory to find a suitabledefault file and then change the url

Release 23041607 - 126 -

Brazil project Developer DocumentationClass DefaultFileHandler SML-2006-0530

Constructor Detail

DefaultFileHandler

public DefaultFileHandler ()

Method Detail

Remember our prefix in the properties tableSpecified by

respond

If the url ends with a look around in the corrosponding directory to find a suitable default file andthen change the urlSpecified by

respond in interface Handler

041607Release 23 - 127 -

Class DefaultFileHandlerBrazil project Developer Documentation SML-2006-0530

ReturnsAlways returns false

Release 23041607 - 128 -

Class DeferredHandlersunlabsbrazilhandler Class DeferredHandler

javalangObject | +-- sunlabsbrazilhandlerDeferredHandler

public class DeferredHandlerextends Objectimplements Handler

Wrap another handler deferring its initialization until request time This allows handlers to be configuredbut not initialized until a first use is attempted

Normally when a handlerrsquos class is first resolved if any of the dependent classes are not available an errorwill occur terminating the server Using this handler other handlers can be conditionally configured basedon the availability of other specified classes at run time

NOTE This functionallity should be integrated into the ChainHandler eliminating the need for thisone

Request Properties handler

The token representing the handler to conditionally configure This is used as the handlerrsquos prefix requires

The names of classes required to be resolvable before configuring the handler [handler]prefix

Used to trigger the configuration [handler]class

The name of the handler class

Constructor SummaryDeferredHandler ()

041607Release 23 - 129 -

Class DeferredHandlerBrazil project Developer Documentation SML-2006-0530

Remember the server for deferred initialization

boolean respond (Request request) Dispatch to the handler installing it if needed

Constructor Detail

DeferredHandler

public DeferredHandler ()

Method Detail

Remember the server for deferred initializationSpecified by

respond

Release 23041607 - 130 -

Brazil project Developer DocumentationClass DeferredHandler SML-2006-0530

Dispatch to the handler installing it if neededSpecified by

041607Release 23 - 131 -

Class DialogHandlersunlabsbrazilhandler Class DialogHandler

All Implemented Interfaces javaxaccessibilityAccessible Handler ImageObserver MenuContainer Serializable

public class DialogHandlerextends Appletimplements Handler

Sample handler for popping up a dialog box on the server This is used for interactive authentication of webpages allowing an operator on the serverrsquos computer to allow or deny access to pages on a per requestbasis Input parameters examined in the request properties prefix suffix glob match

Specify the URL that triggers this handler (See MatchString ) default

The message to appear in the dialog box Defaults to Request from Client denied

The message to appear in the permission denied spot If query data is present it is used as the message

Note This is the only class in the entire system that requires AWT

See Also subspecs()

public boolean match (String str int[] indices)

Release 23041607 - 778 -

For the indices specified below the range extends from the character at the starting index up to but notincluding the character at the ending index

indices[0] and indices[1] are set to starting and ending indices of the range of str thatmatched the entire regular expression

indices[2] and indices[3] are set to the starting and ending indices of the range of str thatmatched the first (leftmost) parenthesized subexpression indices[n 2] and indices[n 2+ 1] are set to the range that matched the nth subexpression and so on

If subexpression n did not match then indices[n 2] and indices[n 2 + 1] are bothset to -1

The length that the caller should use when allocating the indices array is twice the return value of Regexpsubspecs The array can be shorter (in which case not all the information will bereturned) or longer (in which case the remainder of the elements are initialized to -1 ) or null (toignore the subexpressions)Parameters

str - The string to matchindices - An array of integers allocated by the caller and filled in with information about theportions of str that matched all the parts of the regular expression May be null

Returnstrue if the string matched the regular expression false otherwise If false is returned thenthe contents of indices are unchanged

See Also subspecs()

public String sub (String str String subspec)

Matches a string against a regular expression and replaces the first match with the string generatedfrom the substitution parameterParameters

str - The string to match against this regular expressionsubspec - The substitution parameter described in REGULAR EXPRESSION SUBSTITUTION [p ]

ReturnsThe string formed by replacing the first match in str with the string generated from subspec If no matches were found then the return value is null

subAll

041607Release 23 - 779 -

public String subAll (String str String subspec)

Matches a string against a regular expression and replaces all matches with the string generated fromthe substitution parameter After each substutition is done the portions of the string already examinedincluding the newly substituted region are not checked again for new matches -- only the rest of thestring is examinedParameters

ReturnsThe string formed by replacing all the matches in str with the strings generated from subspec If no matches were found then the return value is a copy of str

applySubspec

public static void applySubspec (Regsub rs String subspec StringBuffer sb)

Utility method to give access to the standard substitution algorithm used by sub and subAll Appends to the string buffer the string generated by applying the substitution parameter to the matched regionParameters

rs - Information about the matched regionsubspec - The substitution parametersb - StringBuffer to which the generated string is appended

public String sub (String str RegexpFilter rf)

toString

Returns a string representation of this compiled regular expression The format of the stringrepresentation is a symbolic dump of the bytecodesOverrides

A string representation of this regular expression

Release 23041607 - 780 -

Class Regsubsunlabsbrazilutilregexp Class Regsub

javalangObject | +-- sunlabsbrazilutilregexpRegsub

public class Regsubextends Object

The Regsub class provides an iterator-like object to extract the matched and unmatched portions of astring with respect to a given regular expression

After each match is found the portions of the string already checked are not searched again -- searching forthe next match will begin at the character just after where the last match ended

Here is an example of using Regsub to replace all XX sequences in a string with the ASCII characterrepresented by the hex digits XX

public static void main(String[] args) throws Exception Regexp re = new Regexp([a-fA-F0-9][a-fA-F0-9]) Regsub rs = new Regsub(re args[0])

StringBuffer sb = new StringBuffer()

while (rsnextMatch()) sbappend(rsskipped())

String match = rsmatched()

int hi = Characterdigit(matchcharAt(1) 16) int lo = Characterdigit(matchcharAt(2) 16) sbappend((char) ((hi ltlt 4) | lo)) sbappend(rsrest())

Systemoutprintln(sb)

See Also subspecs()

public boolean match (String str int[] indices)

Release 23041607 - 778 -

For the indices specified below the range extends from the character at the starting index up to but notincluding the character at the ending index

indices[0] and indices[1] are set to starting and ending indices of the range of str thatmatched the entire regular expression

indices[2] and indices[3] are set to the starting and ending indices of the range of str thatmatched the first (leftmost) parenthesized subexpression indices[n 2] and indices[n 2+ 1] are set to the range that matched the nth subexpression and so on

If subexpression n did not match then indices[n 2] and indices[n 2 + 1] are bothset to -1

The length that the caller should use when allocating the indices array is twice the return value of Regexpsubspecs The array can be shorter (in which case not all the information will bereturned) or longer (in which case the remainder of the elements are initialized to -1 ) or null (toignore the subexpressions)Parameters

str - The string to matchindices - An array of integers allocated by the caller and filled in with information about theportions of str that matched all the parts of the regular expression May be null

Returnstrue if the string matched the regular expression false otherwise If false is returned thenthe contents of indices are unchanged

See Also subspecs()

public String sub (String str String subspec)

Matches a string against a regular expression and replaces the first match with the string generatedfrom the substitution parameterParameters

ReturnsThe string formed by replacing the first match in str with the string generated from subspec If no matches were found then the return value is null

subAll

041607Release 23 - 779 -

public String subAll (String str String subspec)

Matches a string against a regular expression and replaces all matches with the string generated fromthe substitution parameter After each substutition is done the portions of the string already examinedincluding the newly substituted region are not checked again for new matches -- only the rest of thestring is examinedParameters

ReturnsThe string formed by replacing all the matches in str with the strings generated from subspec If no matches were found then the return value is a copy of str

applySubspec

public static void applySubspec (Regsub rs String subspec StringBuffer sb)

Utility method to give access to the standard substitution algorithm used by sub and subAll Appends to the string buffer the string generated by applying the substitution parameter to the matched regionParameters

rs - Information about the matched regionsubspec - The substitution parametersb - StringBuffer to which the generated string is appended

public String sub (String str RegexpFilter rf)

toString

Returns a string representation of this compiled regular expression The format of the stringrepresentation is a symbolic dump of the bytecodesOverrides

A string representation of this regular expression

Release 23041607 - 780 -

Class Regsubsunlabsbrazilutilregexp Class Regsub

javalangObject | +-- sunlabsbrazilutilregexpRegsub

public class Regsubextends Object

The Regsub class provides an iterator-like object to extract the matched and unmatched portions of astring with respect to a given regular expression

After each match is found the portions of the string already checked are not searched again -- searching forthe next match will begin at the character just after where the last match ended

Here is an example of using Regsub to replace all XX sequences in a string with the ASCII characterrepresented by the hex digits XX

public static void main(String[] args) throws Exception Regexp re = new Regexp([a-fA-F0-9][a-fA-F0-9]) Regsub rs = new Regsub(re args[0])

StringBuffer sb = new StringBuffer()

while (rsnextMatch()) sbappend(rsskipped())

String match = rsmatched()

int hi = Characterdigit(matchcharAt(1) 16) int lo = Characterdigit(matchcharAt(2) 16) sbappend((char) ((hi ltlt 4) | lo)) sbappend(rsrest())

Systemoutprintln(sb)