Version 4.10.0

hirondelle.web4j
Class BuildImpl

Object
  extended by hirondelle.web4j.BuildImpl

public final class BuildImpl
extends Object

Return concrete instances of configured implementation classes. This is a Service Locator class.

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:

The init(Map) 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's 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 tasks need to be performed after user login? LoginTasks Login example
What Action is related to each request? RequestParser (an ABC) RequestToAction RequestParserImpl
Which requests should be treated as malicious attacks? ApplicationFirewall AppFirewall ApplicationFirewallImpl
Which requests use untrusted proxies for the user id? UntrustedProxyForUserId OwnerFirewall UntrustedProxyForUserIdImpl
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 ConvertParamErrorImpl example
What characters are permitted for text input fields? PermittedCharacters PermittedChars PermittedCharactersImpl
How is a date formatted and parsed? DateConverter DateConverterImpl example
How is a Locale derived from the request? LocaleSource LocaleSrc LocaleSourceImpl
How is the system clock defined? TimeSource TimeSrc TimeSourceImpl
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
Does this request/operation have a data ownership constraint? UntrustedProxyForUserId OwnerFirewall UntrustedProxyForUserIdImpl

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 void adHocImplementationAdd(Class aInterface, Class aImplementationClass)
          Add an implementation - intended for testing only.
static void adHocImplementationRemove(Class aInterface)
          Remove an implementation - intended for testing only.
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 LoginTasks forLoginTasks()
          Return the configured implementation of LoginTasks.
static UntrustedProxyForUserId forOwnershipFirewall()
          Return the configured implementation of UntrustedProxyForUserId.
static PermittedCharacters forPermittedCharacters()
          Return the configured implementation of PermittedCharacters.
static SpamDetector forSpamDetector()
          Return the configured implementation of SpamDetector.
static StartupTasks forStartupTasks()
          Return the configured implementation of StartupTasks.
static TimeSource forTimeSource()
          Return the configured implementation of TimeSource.
static TimeZoneSource forTimeZoneSource()
          Return the configured implementation of TimeZoneSource.
static Translator forTranslator()
          Return the configured implementation of Translator.
static void init(Map<String,String> aConfig)
          Called by the framework upon startup.
static void initDatabaseLayer(Map<String,String> aConfig)
          Intended for contexts outside of normal servlet operation, where the caller wants to use the web4j database and model layer only.
 
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

init

public static void init(Map<String,String> 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 TimeSource and LoggingConfig are treated slightly differently than the rest. Their implementations are found and used earlier than the others, since they are of immediate use.

See class comment for more information.

Parameters:
aConfig - contains information regarding custom implementations, and information for logging config (if any); in a servlet context, this information is extracted by the framework from settings in web.xml.
Throws:
AppException

initDatabaseLayer

public static void initDatabaseLayer(Map<String,String> aConfig)
                              throws AppException
Intended for contexts outside of normal servlet operation, where the caller wants to use the web4j database and model layer only. (For example, a command-line application.) This method uses these interfaces, in the stated order: Usually, the caller will need to supply only one of the above - ConnectionSource. For the other items, the default implementations will usually be adequate, and no action is required.

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.


forLoginTasks

public static LoginTasks forLoginTasks()
Return the configured implementation of LoginTasks.


forConvertParamError

public static ConvertParamError forConvertParamError()
Return the configured implementation of ConvertParamError.


forConvertColumn

public static ConvertColumn forConvertColumn()
Return the configured implementation of ConvertColumn.


forPermittedCharacters

public static PermittedCharacters forPermittedCharacters()
Return the configured implementation of PermittedCharacters.


forConnectionSource

public static ConnectionSource forConnectionSource()
Return the configured implementation of ConnectionSource.


forLocaleSource

public static LocaleSource forLocaleSource()
Return the configured implementation of LocaleSource.


forTimeSource

public static TimeSource forTimeSource()
Return the configured implementation of TimeSource.

When testing, an application may call this method in order to use a 'fake' system time.

Internally, WEB4J will always use this method when it needs the current time. This allows a fake system time to be shared between your application and WEB4J.


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.


forOwnershipFirewall

public static UntrustedProxyForUserId forOwnershipFirewall()
Return the configured implementation of UntrustedProxyForUserId.


adHocImplementationAdd

public static void adHocImplementationAdd(Class aInterface,
                                          Class aImplementationClass)
Add an implementation - intended for testing only.

This method allows testing code to configure a specific implementation class. Example:

BuildImpl.adHocImplementationAdd(TimeSource.class, MyTimeSource.class);
Calls to this method (often in a JUnit setUp() method) should be paired with a subsequent call to adHocImplementationRemove(Class).


adHocImplementationRemove

public static void adHocImplementationRemove(Class aInterface)
Remove an implementation - intended for testing only.

This method allows testing code to configure a specific implementation class. Example:

BuildImpl.adHocImplementationRemove(TimeSource.class);
Calls to this method (often in a JUnit tearDown() method) should be paired with a previous call to adHocImplementationAdd(Class, Class).


Version 4.10.0

Copyright Hirondelle Systems. Published October 19, 2013 - User Guide - All Docs.