hirondelle.web4j
Class BuildImpl

Object
  hirondelle.web4j.BuildImpl

public final class BuildImpl
extends Object

Return concrete instances of configured implementation classes.

WEB4J requires the application programmer to supply concrete implementations of a number of interfaces and a single abstract class. BuildImpl returns instances of those abstractions. Over half of these items have default implementations, which can be used by the application programmer without any configuration effort at all.

When the framework needs a specific implementation, it uses the services of this class. (If the application programmer needs to refer to such an implementation, they have the option of using the methods in this class, instead of referring directly to their implementation.)

Configuration Styles

Concrete implementation classes can be configured in three ways :

• do nothing at all. In this case, a default implementation defined by WEB4J will be used. Several of the WEB4J abstractions (such as ConnectionSource) do not have a default implementation, so this style of configuration is not always possible.
• implement a concrete class of a conventional package and name. The conventional package name is always 'hirondelle.web4j.config', while the conventional class name varies - see below.
• implement a concrete class of a non-conventional package and name, and add an init-param setting to web.xml of the form :

    <init-param>
     <param-name>ImplementationFor.hirondelle.web4j.ApplicationInfo</param-name>
     <param-value>com.xyz.MyAppInfo</param-value>
     <description>
       Package-qualified name of class describing simple, 
       high level information about this application. 
     </description>
    </init-param> 
   

The init(ServletConfig)method will look for implementations in the reverse of the above order. That is,

1. an explicit ImplementationFor.* setting in web.xml
2. a class of a conventional package and name
3. the default WEB4J implementation (if a default implementation exists)

Listing of Interfaces and Conventional Names

Here is a listing of all interfaces used by WEB4J, along with conventional class names, and either a default or example implementation. The package for conventional class names is always 'hirondelle.web4j.config'.

Question	Interface	Conventional Impl Name, in hirondelle.web4j.config	Default/Example Implementation
What is the application's name, version, build date, and so on?	ApplicationInfo	AppInfo	example
What tasks need to be performed during startup?	StartupTasks	Startup	example
What Action is related to each request?	RequestParser (an ABC)	RequestToAction	RequestParserImpl
Which requests should be treated as malicious attacks?	ApplicationFirewall	AppFirewall	ApplicationFirewallImpl
How is spam distinguished from regular user input?	SpamDetector	SpamDetect	SpamDetectorImpl
How is a request param translated into a given target type?	ConvertParam	ConvertParams	ConvertParamImpl
How does the application respond when a low level conversion error takes place when parsing user input?	ConvertParamError	ConvertParamError	example
How is a Date formatted and parsed?	DateConverter	DateConverterImpl	example
How is a Locale derived from the request?	LocaleSource	LocaleSrc	LocaleSourceImpl
How is a TimeZone derived from the request?	TimeZoneSource	TimeZoneSrc	TimeZoneSourceImpl
What is the translation of this text, for a given Locale?	Translator	TranslatorImpl	example
How does the application obtain a database Connection?	ConnectionSource	ConnectionSrc	example
How is a ResultSet column translated into a given target type?	ConvertColumn	ColToObject	ConvertColumnImpl
How should an email be sent when a problem occurs?	Emailer	Email	EmailerImpl
How should the logging system be configured?	LoggingConfig	LogConfig	LoggingConfigImpl

No conflict between the classes of different applications will result, if application code is placed in the usual locations under WEB-INF, and not in shared locations accessible to multiple web applications. Since version 2.2 of the Servlet API, each web application gets its own ClassLoader, so no conflict will result, as long as classes are placed in non-shared locations (which is almost always the case).

This class does not cache objects in any way.

Method Summary

static Object	forAbstraction(String aAbstractionName) Map a fully-qualified aAbstractionName into a concrete implementation.
static Object	forAbstractionPassCtorArgs(String aAbstractBaseClassName, List<Object> aCtorArguments) Map a fully-qualified aAbstractBaseClassName into a concrete implementation.
static ApplicationFirewall	forApplicationFirewall() Return the configured implementation of ApplicationFirewall.
static ApplicationInfo	forApplicationInfo() Return the configured implementation of ApplicationInfo.
static ConnectionSource	forConnectionSource() Return the configured implementation of ConnectionSource.
static ConvertColumn	forConvertColumn() Return the configured implementation of ConvertColumn.
static ConvertParam	forConvertParam() Return the configured implementation of ConvertParam.
static ConvertParamError	forConvertParamError() Return the configured implementation of ConvertParamError.
static DateConverter	forDateConverter() Return the configured implementation of DateConverter.
static Emailer	forEmailer() Return the configured implementation of Emailer.
static LocaleSource	forLocaleSource() Return the configured implementation of LocaleSource.
static SpamDetector	forSpamDetector() Return the configured implementation of SpamDetector.
static StartupTasks	forStartupTasks() Return the configured implementation of StartupTasks.
static TimeZoneSource	forTimeZoneSource() Return the configured implementation of TimeZoneSource.
static Translator	forTranslator() Return the configured implementation of Translator.
static void	init(ServletConfig aConfig) Called by the framework upon startup.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

init

public static void init(ServletConfig aConfig)
                 throws AppException

Called by the framework upon startup.

Extract all configuration which maps names of abstractions to names of corresponding concrete implementations. Confirm both that all required interfaces have configured implementations, and that they can be loaded.

The implementation of LoggingConfig is treated differently than the rest. Since logging upon startup is particularly important, the implementation of LoggingConfig is found first, early in processing. In addition, the implementation is also immediately executed by this class.

See class comment for more information.

Throws:

AppException

forAbstraction

public static Object forAbstraction(String aAbstractionName)

Map a fully-qualified aAbstractionName into a concrete implementation.

This method should only be used for 'non-standard' items not covered by more specific methods in this class. For example, when looking for the implementation of LocaleSource, the forLocaleSource() method should always be used instead of this method.

Implementation classes accessed by this method must have a public no-argument constructor. (This method is best suited for interfaces, and not abstract base classes.)

Uses Class.newInstance(), with no arguments. If a problem occurs, a RuntimeException is thrown.

Parameters:

aAbstractionName - package-qualified name of an interface or abstract base class, as in "hirondelle.web4j.ApplicationInfo".

forAbstractionPassCtorArgs

public static Object forAbstractionPassCtorArgs(String aAbstractBaseClassName,
                                                List<Object> aCtorArguments)

Map a fully-qualified aAbstractBaseClassName into a concrete implementation.

Intended for abstract base classes (ABC's) having a public constructor with known arguments. For example, this method is used by the Controller to build an implementation of RequestParser, by passing in a request and response object. (Implementations of that ABC are always expected to take those two particular constructor arguments.)

If a problem occurs, a RuntimeException is thrown.

Parameters:

aAbstractBaseClassName - package-qualified name of an Abstract Base Class, as in "hirondelle.web4j.ui.RequestParser".

aCtorArguments - List of arguments to be passed to the constructor of an implementation class; the size of this list determines the selected constructor (by matching the number of parameters), and the iteration order of its items corresponds to the order of appearance of the formal constructor parameters.

forApplicationInfo

public static ApplicationInfo forApplicationInfo()

Return the configured implementation of ApplicationInfo.

forStartupTasks

public static StartupTasks forStartupTasks()

Return the configured implementation of StartupTasks.

forConvertParamError

public static ConvertParamError forConvertParamError()

Return the configured implementation of ConvertParamError.

forConvertColumn

public static ConvertColumn forConvertColumn()

Return the configured implementation of ConvertColumn.

forConnectionSource

public static ConnectionSource forConnectionSource()

Return the configured implementation of ConnectionSource.

forLocaleSource

public static LocaleSource forLocaleSource()

Return the configured implementation of LocaleSource.

forTimeZoneSource

public static TimeZoneSource forTimeZoneSource()

Return the configured implementation of TimeZoneSource.

forDateConverter

public static DateConverter forDateConverter()

Return the configured implementation of DateConverter.

forTranslator

public static Translator forTranslator()

Return the configured implementation of Translator.

forApplicationFirewall

public static ApplicationFirewall forApplicationFirewall()

Return the configured implementation of ApplicationFirewall.

forSpamDetector

public static SpamDetector forSpamDetector()

Return the configured implementation of SpamDetector.

forEmailer

public static Emailer forEmailer()

Return the configured implementation of Emailer.

forConvertParam

public static ConvertParam forConvertParam()

Return the configured implementation of ConvertParam.