|
 |
 |
 |
 |
 |
 |
Barracuda - Source Package Structure |
 |
 |
 |
Source
Package StructureThe source tree in this example is structured something like
this:
- org.barracudamvc - Contains A_Changes_History, the
master class which is used to keep track of changes to the Barracuda source tree. If you
modify source, your change should be noted here.
- org.barracudamvc.admin - This package contains
an Admin application that you can extend and use to cycle Barracuda
services in Tomcat. [TODO: need to document
how this works]
- org.barracudamvc.config - This package contains the BConfig
app that can be used to configure Barracuda while it is running. It also serves as an example of how to use components, forms, events, and localization all in one
app!
- org.barracudamvc.core - This package consists of core
Barracuda classes...
- ... .comp - All of the classes in this package provide the
component model functionality. There are several different types of classes in this
package
- Component Classes - the root component is AbstractBComponent which implements the
BContainer interface. There are 11 classes that provide concrete component
implementations. Within this group there are two distinct types:
- Generic components - BComponent, BTemplate, BTable, BList, BText, and BScript
- Specific components - BInput, BToggleButton, BSelect, BAction, and BLink
- View Interfaces & Implementations - every component must be bound to at least
one view (linking it to a node in the DOM). There are 4 specific types of views:
- View (this is the default)
- TemplateView (used by BTemplate)
- TableView (used by BTable)
- Model Interfaces & Implementations - there are actually only 5 different
model interfaces:
- TemplateModel and IterativeModel (both used by BTemplate)
- TableModel (used by BTable)
- ListModel (used by BList and BSelect)
- ListSelectionModel (used by BSelect)
- ViewContext - the ViewContext is a special kind of class. It describes the
characteristics of the client view and gets passed into the Model implementations so that
the components can render themselves properly.
- Exceptions - all exceptions thrown by the component model are based off of
RenderException
- ... .helper - This subpackage contains several commonly used
helper classes
- ComponentGateway - a servlet you can use if you wish to use components all by
themselves (apart from the event model)
- BTemplateGateway - an extension of ComponentGateway especially designed for
working with template components. All you have to do is instantiate the class with
the name of the template and a reference to the model; it takes care of the rest
- FormGateway - a class which provides some very simple redirect functionality for
form actions. Developers typically will not need to use this class.
- ... .model - This subpackage defines several key model
interfaces used by concrete Barracuda models/components.
- ... .renderer - This subpackage acts as the root location of
rendering related classes that are common to all flavors of markup.
- Renderer and RendererFactory - define the basic rendering interfaces
- DefaultDOMRenderer - defines the parent renderer implementation that all concrete
renderers ultimately extend from
- TemplateHelper - contains the logic used by the BTemplate component renderers to
actually parse a template and render the results into the DOM
- ... .html - This subpackage is responsible for rendering
components into HTML views
- ... .wml - This subpackage is responsible for rendering
components into WML views (note that this package hasn't really been implemented yet)
- ... .xml - This subpackage is responsible for rendering
components into XML views
- ... .scripting - This subpackage defines several key
components that are used to enable Barracuda scripting
support.
- ... .event - All of the classes in this package provide
Barracuda's event model functionality. There are several different types of classes in
this package:
- ApplicationAssembler - a class that dynamically assembles a hierarchy of event
gateways from an XML descriptor file.
- ApplicationGateway - the servlet that would get extended for specific
implementations of the event model. Developers will typically just reference this class in
their web.xml file.
- Event Model interfaces - there are 12 of these, and they define the fundamental
entities within the event model. See the Event Model
Topology for a detailed explanation of what each interface does.
- Default Implementations - most of these interfaces have a default implementation.
The naming convention is generally Default<interfaceName>. Most frequently,
developers will interact with:
- DefaultEventGateway - the base class a developer extends when writing a master
class that will contain event handling code
- DefaultBaseEventListener - the base class a developer will extend when writing
inner class "event listeners" to handle events within an event gateway class.
Developers will typically override either handleControlEvent() or handleViewEvent()
methods.
- Events - BaseEvent, RequestEvent, ResponseEvent, HttpRequestEvent and
HttpResponseEvent.
- Exceptions - All the exceptions which get thrown by the event model are based off
of EventException.
- ... .events - This subpackage defines a generic ActionEvent
(which some of the components are capable of generating on the client side)
- ... .helper - This subpackage contains simply
"helper" classes that are sometimes useful in working with the event model.
There are several worth noting:
- DefaultViewHandler - A default implementation that is useful for views which will
be utilizing the ComponentModel. Analogous to ComponentGateway.
- BTemplateViewHandler - Extends DefaultViewHandler with an implementation that is
tailored for using BTemplate components to render a view. All you have to do is
instantiate the class with the name of the template and a reference to the model; it
takes care of the rest.
- EventConnectorFactory - Convenient way to register
event handlers for a specific event. Only works for
handlers that are top level classes, -OR- public static
inner classes.
- EventForwardingFactory - Simply handles an event by firing another
event, effectively "forwarding" program flow. Very useful when ControlEvent
handlers don't do any custom processing (ie. they just fire a
ViewEvent)
- EventRedirectFactory - Similar to the
EventForwardingFactory, except that it fires a client
side redirect instead of just adding the specified event
to the queue.
- AbstractBlockIterator - This class provides an
abstract implementation of BlockIterate interface, which
is used by BlockIterateHandler to efficiently process
very large DOMs in chunks. Basically, you would use this
handler when you want to render a page in iterative
chunks, to avoid the memory issues of processing a large
page all at once.
- ... .forms - All the classes in this package are used for form
mapping and validation. There are several key entities:
- FormMap - this interface defines a virtual "form". Forms can be
"mapped" (either from a servlet request, or from a statemap) and
"validated".
- FormElement - form elements are used to define the actual "element"
objects in a form. You instantiate form elements and add them to a form.
- FormType - defines all known types of form elements
- FormValidator - a validator is an object that is used to validate either a form
or a form element. A form map can have an unlimited number of validators, and each form
element may be bound to a specific validator as well. Validators also act as containers,
allowing them to contain any number of other validators, each of which will be recursively
invoked when the root validator is asked to "validate" something.
- Logical validators - There are several predefined "logical" validators:
- And - validates to true if two validators are both true
- Or - validates to true if at least one of two validators is true
- Not - validates to true if a validator is not true
- Exceptions - when a validator encounters something invalid, it throws a
validation exception, which stops all validation and returns program flow to whatever
invoked the validation. Note that by throwing a DeferredValidationException, the
validation process continues until all validators have been given the opportunity to
validate the data. THis gives you the ability to get a whole bunch of errors in one pass.
- ... .validators - sample reusable validators for basic
validation needs. There are a number of generic validators:
- NotNullValidator - ensures a value is not null
- ValidTypeValidator - ensures a value is a valid type
- EqualsValidator - checks for equality
- MaxLengthValidator - ensures max length
- MinLengthValidator - ensures min length
- RangeValidator - ensures value is in a given range of values
- DigitValidator - ensures a value contains only digits
- DateValidator - ensures a value is a valid date
- DateRangeValidator - ensures a value falls within a date range
- ... .helper - Contains some simple helper classes that are used
by other Barracuda packages
- ... .scripts - Contains Barracuda scripts that are included in
the Barracuda Jar file and may be used by certain components. The only script we are
currently using is jsrsClientServerHTTPLib.js, which facilitates back button disabling
support.
- ... .util - General utility classes (note that these are
packages into a standalone "Plankton" jar for easy use in other projects).
- ... .data - All this classes in this package relate to
"data" functionality (something used by both the event package and the forms
package). There are several types of classes:
- ReferenceFactory - a ReferenceFactory is an interface used to create a Reference
(Soft, Weak, etc) to an object
- StateMap - the actual statemap interface
- StateMap implementations - there are a number of implementations that all
implement statemap. These are commonly used to view other types of data structures as
statemaps.
- Collections classes - There are several concrete classes (PArrayList and
PHashMap) which implement a common PData interface. These collections classes inherantly
define parents in can carry state (since they ultimately extend from the StateMap
interface). There is also a convenient Param (key/value) class.
- ... .dom - This package provides DOM related services. There are
several key classes:
- DOMFactory - actually loads an XMLC generated DOM object
- DOMLoader - loads a DOM object based on class name + target locale
- DOMWriter - writes out a DOM structure. This class supports pretty printing,
component visibility, and will automatically set the content type for you.
- Default Implementations - each of these interfaces has a default implementation,
which is probably what developers will use most frequently.
- ... .io - This subpackage is needed to provide visibility
support to the DOMWriter class (so that it we set a component's visibility to false, the
DOM nodes that component is bound to will not be rendered). Eventually, these
customizations will be incorporated back into XMLC and this package will go away.
- ... .exceptions - Provides a commonly used NestableException
base class, along with utilities to extract root exception information.
- ... http - HTTP utilitiy classes. The most commonly used will be
ContextServices and SessionServices. These two classes make it very easy for developers to
access servlet context and session information respectively.
- ... .l10n - Localization utility classes, convenient for
retrieving localized data from a property file.
- ... .logging - Utility classes for Log4J logging.
- ... .srv - Utility classes to make it easy to search an object
hierarchy for classes that implement a specific interface.
- ... xml - Utility classes to convert from XML Unicode toe Java
Strings and vica-versa.
- ... .view - This package defines the various entities needed to
describe a client view. There are several key classes:
- ViewCapabilities - container class that provides access to ClientType,
FormatType, ViewType, and client locale
- FormatType - defines the various markup formats
- ClientType - defines the various types of clients
- ScriptingType - defines the various scripting types
- ViewUtil - utility class to parse an HTTPServletRequest and determine the
associated type information
- org.barracudamvc.examples - All Barracuda examples go under
here...
- ... .ex1 - The Simple Login App example
- ... .ex3 - Polymorphic throughput test
- ... .ex4 - Application Assembly test
- ... .xmlc - XMLC specific examples. Some of these actually serve
as simple component test cases.
- org.barracudamvc.taskdefs - Custom Barracuda taskdef code.
Barracuda currently offers several useful taskdefs:
- CopyAndReplace - copys files from mockup directories into XMLC directories and
performs a text substitution on them
- Localize - extends the basic XMLC taskdef to automatically generate localized
templates and then compiles them.
- EventBuilder - creates a Barracuda event hierarchicy from an XML descriptor file
and then compiles the generated classes.
- org.barracudamvc.tutorials - Basic tutorial examples to
help developers understand how to use the Barracuda component model.
|
 |
 |
 |
 |
 |
 |
For all the latest information on
Barracuda, please refer to http://barracudamvc.org
Questions, comments, feedback? Let
us know... |
|