org.apache.click.service
Class XmlConfigService

java.lang.Object
  org.apache.click.service.XmlConfigService

All Implemented Interfaces:

ConfigService, EntityResolver

public class XmlConfigService
extends Object
implements ConfigService, EntityResolver

Provides a Click XML configuration service class.

This class reads Click configuration information from a file named click.xml. The service will first lookup the click.xml under the applications WEB-INF directory, and if not found attempt to load the configuration file from the classpath root.

Configuring Click through the click.xml file is the most common technique.

However you can instruct Click to use a different service implementation. Please see ConfigService for more details.

Nested Class Summary

static class

XmlConfigService.ExcludePage Provide an Excluded Page class.

Nested classes/interfaces inherited from interface org.apache.click.service.ConfigService

ConfigService.AutoBinding

Field Summary

Fields inherited from interface org.apache.click.service.ConfigService

CONTEXT_NAME, ERROR_PATH, MODE_DEBUG, MODE_DEVELOPMENT, MODE_PRODUCTION, MODE_PROFILE, MODE_TRACE, NOT_FOUND_PATH

Constructor Summary

XmlConfigService()

Method Summary

Format	createFormat() Create and return a new format object instance.
String	getApplicationMode() Return the application mode String value: ["production", "profile", "development", "debug"].
ConfigService.AutoBinding	getAutoBindingMode() Return the page auto binding mode.
String	getCharset() Return the Click application charset or null if not defined.
Class<? extends Page>	getErrorPageClass() Return the error handling page Page Class.
FileUploadService	getFileUploadService() Return the application file upload service, which is used to parse multi-part file upload post requests.
Locale	getLocale() Return the Click application locale or null if not defined.
LogService	getLogService() Return the application log service.
MessagesMapService	getMessagesMapService() Return the application messages map service.
Class<? extends Page>	getNotFoundPageClass() Return the page not found Page Class.
Class<? extends Page>	getPageClass(String path) Return the page Class for the given path.
protected Class<? extends Page>	getPageClass(String pagePath, String pagesPackage) Find and return the page class for the specified pagePath and pagesPackage.
List	getPageClassList() Return the list of configured page classes.
Field	getPageField(Class<? extends Page> pageClass, String fieldName) Return the bindable field of the given name for the pageClass, or null if not defined.
Field[]	getPageFieldArray(Class<? extends Page> pageClass) Return an array bindable for the given page class.
Map<String,Field>	getPageFields(Class<? extends Page> pageClass) Return Map of bindable fields for the given page class.
Map<String,Object>	getPageHeaders(String path) Return the headers of the page for the given path.
List<PageInterceptor>	getPageInterceptors() Return the list of configured PageInterceptors instances.
String	getPagePath(Class<? extends Page> pageClass) Return the path for the given page Class.
ResourceService	getResourceService() Return the application resource service.
ServletContext	getServletContext() Return the application servlet context.
TemplateService	getTemplateService() Return the application templating service.
boolean	isJspPage(String path) Return true if JSP exists for the given ".htm" path.
boolean	isProductionMode() Return true if the application is in "production" mode.
boolean	isProfileMode() Return true if the application is in "profile" mode.
protected boolean	isResourcesDeployable() Returns true if Click resources (JavaScript, CSS, images etc) packaged in jars can be deployed to the root directory of the webapp, false otherwise.
boolean	isTemplate(String path) Return true if the given path is a Page class template, false otherwise.
void	onDestroy() Destroy the ConfigurationService.
void	onInit(ServletContext servletContext) Initialize the ConfigurationService with the given application servlet context.
InputSource	resolveEntity(String publicId, String systemId) This method resolves the click.dtd for the XML parser using the classpath resource: /org/apache/click/click.dtd.

Methods inherited from class java.lang.Object

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

Constructor Detail

XmlConfigService

public XmlConfigService()

Method Detail

onInit

public void onInit(ServletContext servletContext)
            throws Exception

Description copied from interface: ConfigService

Initialize the ConfigurationService with the given application servlet context.

This method is invoked after the ConfigurationService has been constructed.

Specified by:

onInit in interface ConfigService

Parameters:

servletContext - the application servlet context

Throws:

Exception - if an error occurs initializing the application

See Also:

ConfigService.onInit(ServletContext)

onDestroy

public void onDestroy()

Description copied from interface: ConfigService

Destroy the ConfigurationService. This method will also invoke the onDestroy() methods on the FileUploadService, TemplateService, ResourceService and the LogService in that order.

Specified by:

onDestroy in interface ConfigService

See Also:

ConfigService.onDestroy()

getApplicationMode

public String getApplicationMode()

Return the application mode String value: ["production", "profile", "development", "debug"].

Specified by:

getApplicationMode in interface ConfigService

Returns:

the application mode String value

getCharset

public String getCharset()

Description copied from interface: ConfigService

Return the Click application charset or null if not defined.

Specified by:

getCharset in interface ConfigService

Returns:

the application character encoding

See Also:

ConfigService.getCharset()

getFileUploadService

public FileUploadService getFileUploadService()

Description copied from interface: ConfigService

Return the application file upload service, which is used to parse multi-part file upload post requests.

Specified by:

getFileUploadService in interface ConfigService

Returns:

the FileUpload service

See Also:

ConfigService.getFileUploadService()

getLogService

public LogService getLogService()

Description copied from interface: ConfigService

Return the application log service.

Specified by:

getLogService in interface ConfigService

Returns:

the application log service.

See Also:

ConfigService.getLogService()

getResourceService

public ResourceService getResourceService()

Description copied from interface: ConfigService

Return the application resource service.

Specified by:

getResourceService in interface ConfigService

Returns:

the resource service

See Also:

ConfigService.getResourceService()

getTemplateService

public TemplateService getTemplateService()

Description copied from interface: ConfigService

Return the application templating service.

Specified by:

getTemplateService in interface ConfigService

Returns:

the template service

See Also:

ConfigService.getTemplateService()

getMessagesMapService

public MessagesMapService getMessagesMapService()

Description copied from interface: ConfigService

Return the application messages map service.

Specified by:

getMessagesMapService in interface ConfigService

Returns:

the messages map service

See Also:

ConfigService.getMessagesMapService()

createFormat

public Format createFormat()

Description copied from interface: ConfigService

Create and return a new format object instance.

Specified by:

createFormat in interface ConfigService

Returns:

a new format object

See Also:

ConfigService.createFormat()

getLocale

public Locale getLocale()

Description copied from interface: ConfigService

Return the Click application locale or null if not defined.

Specified by:

getLocale in interface ConfigService

Returns:

the application locale

See Also:

ConfigService.getLocale()

getAutoBindingMode

public ConfigService.AutoBinding getAutoBindingMode()

Description copied from interface: ConfigService

Return the page auto binding mode. If the mode is "PUBLIC" any public Page fields will be auto bound, if the mode is "ANNOTATION" any Page field with the "Bindable" annotation will be auto bound and if the mode is "NONE" no Page fields will be auto bound.

Specified by:

getAutoBindingMode in interface ConfigService

Returns:

the Page field auto binding mode { PUBLIC, ANNOTATION, NONE }

See Also:

ConfigService.getAutoBindingMode()

isProductionMode

public boolean isProductionMode()

Description copied from interface: ConfigService

Return true if the application is in "production" mode.

Specified by:

isProductionMode in interface ConfigService

Returns:

true if the application is in "production" mode

See Also:

ConfigService.isProductionMode()

isProfileMode

public boolean isProfileMode()

Description copied from interface: ConfigService

Return true if the application is in "profile" mode.

Specified by:

isProfileMode in interface ConfigService

Returns:

true if the application is in "profile" mode

See Also:

ConfigService.isProfileMode()

isJspPage

public boolean isJspPage(String path)

Description copied from interface: ConfigService

Return true if JSP exists for the given ".htm" path.

Specified by:

isJspPage in interface ConfigService

Parameters:

path - the Page ".htm" path

Returns:

true if JSP exists for the given ".htm" path

See Also:

ConfigService.isJspPage(String)

isTemplate

public boolean isTemplate(String path)

Return true if the given path is a Page class template, false otherwise. By default this method returns true if the path has a .htm or .jsp extension.

If you want to map alternative templates besides .htm and .jsp files you can override this method and provide extra checks against the given path whether it should be added as a template or not.

Below is an example showing how to allow .xml paths to be recognized as Page class templates.

 public class MyConfigService extends XmlConfigService {

     protected boolean isTemplate(String path) {
         // invoke default implementation
         boolean isTemplate = super.isTemplate(path);

         if (!isTemplate) {
             // If path has an .xml extension, mark it as a template
             isTemplate = path.endsWith(".xml");
         }
         return isTemplate;
     }
 } 

Here is an example web.xml showing how to configure a custom ConfigService through the context parameter config-service-class. We also map *.xml requests to be routed through ClickServlet:

 <web-app xmlns="http://java.sun.com/xml/ns/j2ee"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
   version="2.4">

   <!-- Specify a custom ConfigService through the context param 'config-service-class' -->
   <context-param>
     <param-name>config-service-class</param-name>
     <param-value>com.mycorp.service.MyConfigSerivce</param-value>
   </context-param>

   <servlet>
     <servlet-name>ClickServlet</servlet-name>
     <servlet-class>org.apache.click.ClickServlet</servlet-class>
     <load-on-startup>0</load-on-startup>
   </servlet>

   <!-- NOTE: we still map the .htm extension -->
   <servlet-mapping>
     <servlet-name>ClickServlet</servlet-name>
     <url-pattern>*.htm</url-pattern>
   </servlet-mapping>

   <!-- NOTE: we also map .xml extension in order to route xml requests to the ClickServlet -->
   <servlet-mapping>
     <servlet-name>ClickServlet</servlet-name>
     <url-pattern>*.xml</url-pattern>
   </servlet-mapping>

   ...

 </web-app> 

Please note: even though you can add extra template mappings by overriding this method, it is still recommended to keep the default .htm mapping by invoking super.isTemplate(String). The reason being that Click ships with some default templates such as ConfigService.ERROR_PATH and ConfigService.NOT_FOUND_PATH that must be mapped as .htm.

Please see the ConfigService javadoc for details on how to configure a custom ConfigService implementation.

Specified by:

isTemplate in interface ConfigService

Parameters:

path - the path to check if it is a Page class template or not

Returns:

true if the path is a Page class template, false otherwise

See Also:

ConfigService.isTemplate(String)

getPageClass

public Class<? extends Page> getPageClass(String path)

Description copied from interface: ConfigService

Return the page Class for the given path. The path must start with a "/".

Specified by:

getPageClass in interface ConfigService

Parameters:

path - the page path

Returns:

the page class for the given path or null if no class is found

See Also:

ConfigService.getPageClass(String)

getPagePath

public String getPagePath(Class<? extends Page> pageClass)

Description copied from interface: ConfigService

Return the path for the given page Class.

Specified by:

getPagePath in interface ConfigService

Parameters:

pageClass - the page class

Returns:

path the page path or null if no path is found

Throws:

IllegalArgumentException - if the Page Class is not configured with a unique path

See Also:

ConfigService.getPagePath(Class)

getPageClassList

public List getPageClassList()

Description copied from interface: ConfigService

Return the list of configured page classes.

Specified by:

getPageClassList in interface ConfigService

Returns:

the list of configured page classes

See Also:

ConfigService.getPageClassList()

getPageHeaders

public Map<String,Object> getPageHeaders(String path)

Description copied from interface: ConfigService

Return the headers of the page for the given path.

Specified by:

getPageHeaders in interface ConfigService

Parameters:

path - the path of the page

Returns:

a Map of headers for the given page path

See Also:

ConfigService.getPageHeaders(String)

getNotFoundPageClass

public Class<? extends Page> getNotFoundPageClass()

Description copied from interface: ConfigService

Return the page not found Page Class.

Specified by:

getNotFoundPageClass in interface ConfigService

Returns:

the page not found Page Class

See Also:

ConfigService.getNotFoundPageClass()

getErrorPageClass

public Class<? extends Page> getErrorPageClass()

Description copied from interface: ConfigService

Return the error handling page Page Class.

Specified by:

getErrorPageClass in interface ConfigService

Returns:

the error handling page Page Class

See Also:

ConfigService.getErrorPageClass()

getPageField

public Field getPageField(Class<? extends Page> pageClass,
                          String fieldName)

Description copied from interface: ConfigService

Return the bindable field of the given name for the pageClass, or null if not defined.

Specified by:

getPageField in interface ConfigService

Parameters:

pageClass - the page class

fieldName - the name of the field

Returns:

the public field of the pageClass with the given name or null

See Also:

ConfigService.getPageField(Class, String)

getPageFieldArray

public Field[] getPageFieldArray(Class<? extends Page> pageClass)

Description copied from interface: ConfigService

Return an array bindable for the given page class.

Specified by:

getPageFieldArray in interface ConfigService

Parameters:

pageClass - the page class

Returns:

an array public fields for the given page class

See Also:

ConfigService.getPageFieldArray(Class)

getPageFields

public Map<String,Field> getPageFields(Class<? extends Page> pageClass)

Description copied from interface: ConfigService

Return Map of bindable fields for the given page class.

Specified by:

getPageFields in interface ConfigService

Parameters:

pageClass - the page class

Returns:

a Map of public fields for the given page class

See Also:

ConfigService.getPageFields(Class)

getPageInterceptors

public List<PageInterceptor> getPageInterceptors()

Description copied from interface: ConfigService

Return the list of configured PageInterceptors instances.

Specified by:

getPageInterceptors in interface ConfigService

Returns:

the list of configured PageInterceptor instances

See Also:

ConfigService.getPageInterceptors()

getServletContext

public ServletContext getServletContext()

Description copied from interface: ConfigService

Return the application servlet context.

Specified by:

getServletContext in interface ConfigService

Returns:

the application servlet context

See Also:

ConfigService.getServletContext()

resolveEntity

public InputSource resolveEntity(String publicId,
                                 String systemId)
                          throws SAXException,
                                 IOException

This method resolves the click.dtd for the XML parser using the classpath resource: /org/apache/click/click.dtd.

Specified by:

resolveEntity in interface EntityResolver

Parameters:

publicId - the DTD public id

systemId - the DTD system id

Returns:

resolved entity DTD input stream

Throws:

SAXException - if an error occurs parsing the document

IOException - if an error occurs reading the document

See Also:

EntityResolver.resolveEntity(String, String)

getPageClass

protected Class<? extends Page> getPageClass(String pagePath,
                                             String pagesPackage)

Find and return the page class for the specified pagePath and pagesPackage.

For example if the pagePath is '/edit-customer.htm' and package is 'com.mycorp', the matching page class will be: com.mycorp.EditCustomer or com.mycorp.EditCustomerPage.

If the page path is '/admin/add-customer.htm' and package is 'com.mycorp', the matching page class will be: com.mycorp.admin.AddCustomer or com.mycorp.admin.AddCustomerPage.

Parameters:

pagePath - the path used for matching against a page class name

pagesPackage - the package of the page class

Returns:

the page class for the specified pagePath and pagesPackage

isResourcesDeployable

protected boolean isResourcesDeployable()

Returns true if Click resources (JavaScript, CSS, images etc) packaged in jars can be deployed to the root directory of the webapp, false otherwise.

By default this method will return false in restricted environments where write access to the underlying file system is disallowed. Example environments where write access is not allowed include the WebLogic JEE server and Google App Engine. (Note: WebLogic provides the property "Archived Real Path Enabled" that controls whether web applications can access the file system or not. See the Click user manual for details).

Returns:

true if resources can be deployed, false otherwise