Barracuda - Source Package Structure
barracuda.gif (11456 bytes)Source 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. [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...