/src_docs/architecture/vision.html, v125
Package Structure
The 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. [I don't believe this is used anymore - csc]
- 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.
Last Modified: 2006-01-02 15:59:13 -0500 (Mon, 02 Jan 2006)