Principles of HybridJava Component Model
1. The MVC paradigm
Web application components are reusable presentation layer modules that follow the MVC paradigm. So, each component incorporates its own Controller, its own View and (state of) its own Model.
2. The One Touch principle
Using a component to build a page or another component is as simple as using an HTML tag, and does not require any programming or configuration. At the runtime the framework cares about dispatching information from request parameters to appropriate component instances and back from component instances to the response sent to the client. Developers do not care about assigning IDs to components.
3. Session Scope Persistence
By default the framework keeps the state of each component until the session expires. This behavior does not depend on the sequence of the pages shown or on component's visibility on the pages.
4. In-page Reusability and Inter-page Sharing
A component may be used in a page (or containing component) more than once. For each use the framework must support an independent state. That is true for components used in the loop as well. A component may be declared as shared between several pages. Then, only one instance should be created by the framework for all the Views of that component.
5. Inter-Component Communication
At the View phase a component/page may pass information to contained components via widget parameters. At the Controller phase the framework API should support a properly ordered communication between a component and containing component/page. A page or a containing component doesn't need to know anything about the contained component in advance.
Note that site developer works only within green areas. All the rest is already implemented in the framework. This way no additional programming nor configuration is necessary to use components.
Framework Implementation Details
Let us consider a hypothetical page PageName. The View of this page is coded in PageName.page file in HybridJava language. Each page has a corresponding page state class PageName_PS. The framework keeps instances of page state classes in the session, so all instance data members of a page state class are session-persistent. The $handle method of PageName_PS class is called by the framework when an HTTP request addressed to this page arrives.
HybridJava Compiler introspects the page state class, parses the page View file and generates class PageName_P (presentation class). This generated class contains method $render which, when executed by framework, provides HTML output sent to the client. Presentation class is generated as derived from the page state class, so all the non-private members and methods of the latter are directly accessible in the presentation class.
Widgets and Components
Let us consider a widget WidgetName. The View of this widget is coded in WidgetName.widget file in HybridJava language. A component is a widget View, associated (by name) with class WidgetName_WS (widget state class a.k.a. component state class). The framework keeps instances of component state classes in the session, so all instance data members of a widget state class are session-persistent. The $handleComponent method of this class is called by the framework whenever an HTTP request addressed to the page arrives, but before the $handle method is called. The $handleComponent method of a component is called by the framework before $handleComponent of containing component.
HybridJava Compiler introspects the component state class, parses the component View file, and generates corresponding Java code as one or several parts of the $render method (mentioned above) of the page presentation class, so all page state data is directly accessible in the widget View code. Component state class data is also accessible in the component View code.
For pure View components (when components state class is not defined) no instances are created, so such components are truly lightweight. No tree of components is built at the runtime.
All page and component presentation data is stored in a single copy accessible both from View code and Controller code. Thus, there is no need to use JavaBeans, or to deal with data synchronization.
The framework cares about dispatching information coded in HTTP request parameters to appropriate component handlers or to the page handler.This works even under multiple loops and/or recursion.
Component handlers have to extract data from HTTP parameters using method $getParam. This method is similar to getParameter method of ServletRequest, except that only values originating from the View of the given component instance are accessible.
Handlers communicate to business layer and change the component/page presentation state data. Redirection is not used to move to the next page - after the call to $handle method the framework calls the $render method of the page to be shown next.
The JavaDoc of the framework API is available here. HybridJava Framework API is wrapped around J2EE Servlet API and, compared to the latter, operates on higher level entities: application, pages, and components, though Request and Session objects are still available.
Implementation of Ajax component-oriented support, "return to previous page" (method $setReturn), validation (methods $setBadParam and badParam) and signals (methods $accept, $send, $recend) all belong to the run-time only. You may consider these features as a part of example and having the source of the run-time are free to remove them or re-implement the way you like.
HybridJava technology does not enforce any specific Servlet class. The SampleServlet class provided with the Sample Application is indeed just a sample of usage. It is sufficient to have just one Servlet per application.
HybridJava Compiler generates try-catch blocks at the page level and at each widget level separately. This isolates server from specific pages, pages from widgets and widgets from other widgets in case of exception even if the developer did not care about that.