PAJES 3.0.21

org.pajes.html
Class PajeFactory

java.lang.Object
  extended by org.pajes.html.PajeFactory
Direct Known Subclasses:
TreeFactory

public class PajeFactory
extends java.lang.Object

Combines a PajeTemplate with one or more source HTML files.

The factory can determine if the request should return an internationalised version of a Paje, and automatically locate and return the most preferred international version. By default, this facility is enabled.

The factory can also automatically detect when a source HTML file changes, and regenerate the internal representation that will be returned by the create(javax.servlet.http.HttpServletRequest) methods. Again, this facility is enabled by default.

See Also:
Paje, PajeTemplate, PajeResource

Nested Class Summary
protected  class PajeFactory.Document
          Inner class representing a source HTML document and it's generated form.
 
Field Summary
static java.lang.String CHECK_FOR_FILE_CHANGES_ATTRIBUTE
          Context attribute to set whether checking for modifications to the source HTML files is turned on or off by default.
static java.lang.String INTERNATIONALISATION_ATTRIBUTE
          Context attribute to set whether internationalisation is turned on or off by default.
 
Constructor Summary
PajeFactory(PajeTemplate template, PajeResource resource)
          Creates a factory that will create Paje objects based on the specified PajeTemplate.
PajeFactory(PajeTemplate template, javax.servlet.ServletContext context, java.lang.String pathPattern)
          Creates a factory that will create Paje objects based on the specified PajeTemplate.
 
Method Summary
 void addResource(java.lang.String key, PajeResource resource)
          Adds a new source file or source file collection to which this factory's template can be applied.
 void addResource(java.lang.String key, javax.servlet.ServletContext context, java.lang.String pathPattern)
          Adds a new source file or source file collection to which this factory's template can be applied.
 Paje create(javax.servlet.http.HttpServletRequest request)
          Creates a new localized Paje object from the base document defined for this factory.
protected  Paje create(java.text.MessageFormat keyBase, java.util.Enumeration<?> locales, PajeFactory.Document defaultDocument)
          Creates a new localized Paje object.
 Paje create(java.lang.String[] keys, java.lang.String[] arguments, javax.servlet.http.HttpServletRequest request)
          Creates a new localized Paje object from the source file added to this factory by the addResource(java.lang.String, org.pajes.html.PajeResource) method.
 Paje create(java.lang.String key, java.lang.String[] arguments, javax.servlet.http.HttpServletRequest request)
          Creates a new localized Paje object from the source file added to this factory by the addResource(java.lang.String, org.pajes.html.PajeResource) method.
protected  PajeFactory.Document find(java.text.MessageFormat keyBase, java.util.Enumeration<?> locales, PajeFactory.Document defaultDocument)
          Creates a new localized Paje object.
protected  PajeFactory.Document find(PajeResource resource, java.lang.String[] arguments)
          Finds the PajeFactory.Document object from the source file added to this factory by the addResource(java.lang.String, org.pajes.html.PajeResource) method.
protected  PajeResource find(java.lang.String key)
          Finds the base PajeResource object from added to this factory by the addResource(java.lang.String, org.pajes.html.PajeResource) method.
protected  java.text.MessageFormat getKeyBase(PajeResource resource, java.lang.String[] arguments)
          Returns a MessageFormat pattern suitable for creating localized paths.
 PajeResource getPajeResource(java.lang.String key)
          Returns the requested PajeResource.
protected  javax.servlet.ServletContext getServletContext()
          Returns the servlet context used by this factory.
 PajeTemplate getTemplate()
          Returns the template object used to generate Pajes.
 void setDestroyAfterWrite(boolean destroy)
          Sets the default value for Paje.setDestroyAfterWrite(boolean) for each Paje generated by this factory.
 PajeFactory setFileModificationChecking(boolean on)
          Determines whether any checks should be made to see if any of the HTML source files managed by this factory have changed.
 PajeFactory setInternationalisationChecking(boolean on)
          Determines whether any checks should be made to see if an internationalised version of the requested file Paje exists.
 void setTemplate(PajeTemplate template)
          Sets the template object used to generate Paje objects.
 java.lang.String toString()
          Returns a String representation of this resource.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

CHECK_FOR_FILE_CHANGES_ATTRIBUTE

public static final java.lang.String CHECK_FOR_FILE_CHANGES_ATTRIBUTE
Context attribute to set whether checking for modifications to the source HTML files is turned on or off by default.

See Also:
setFileModificationChecking(boolean), Constant Field Values

INTERNATIONALISATION_ATTRIBUTE

public static final java.lang.String INTERNATIONALISATION_ATTRIBUTE
Context attribute to set whether internationalisation is turned on or off by default.

See Also:
setInternationalisationChecking(boolean), Constant Field Values
Constructor Detail

PajeFactory

public PajeFactory(PajeTemplate template,
                   PajeResource resource)
            throws java.io.IOException,
                   TagException
Creates a factory that will create Paje objects based on the specified PajeTemplate.

Parameters:
template - the PajeTemplate object from which Paje instances will be generated.
resource - the base resource to be returned by this factory. This resource MUST NOT use replaceable parameters in its path pattern.
Throws:
java.io.IOException - if an IO exception occurs.
TagException - if the specified PajeResource cannot be located.

PajeFactory

public PajeFactory(PajeTemplate template,
                   javax.servlet.ServletContext context,
                   java.lang.String pathPattern)
            throws java.io.IOException
Creates a factory that will create Paje objects based on the specified PajeTemplate.

Parameters:
template - the PajeTemplate object from which Paje instances will be generated.
context - the servlet context which will be requested to return the resource represented by the pathPattern.
pathPattern - the path pattern of the resource. This resource MUST NOT use replaceable parameters.
Throws:
java.io.IOException - if an IO exception occurs.
Method Detail

addResource

public void addResource(java.lang.String key,
                        PajeResource resource)
Adds a new source file or source file collection to which this factory's template can be applied.

Parameters:
key - the key which will uniquely identify this source file.
resource - the resource collection identified by this key.

addResource

public void addResource(java.lang.String key,
                        javax.servlet.ServletContext context,
                        java.lang.String pathPattern)
Adds a new source file or source file collection to which this factory's template can be applied.

Parameters:
key - the key which will uniquely identify this source file.
context - the servlet context which will be requested to return the resource represented by the pathPattern.
pathPattern - the path pattern of the resource collection.

create

public Paje create(javax.servlet.http.HttpServletRequest request)
            throws java.io.IOException
Creates a new localized Paje object from the base document defined for this factory. The following processing logic is used to attempt to locate a localized version of the requested resource:
  1. Separate the [file name] portion and the [file type] portion of the base resource, using the final period (".") in the path as the delimiter.
  2. For each locale specified on the request, and in preference order:
    1. Determine if a resource exists with a name constructed as:
       
             [file name]_language_country_variant.[file type]
        
       
      If such a resource exists, return the URL and stop further processing.
    2. Determine if a resource exists with a name constructed as:
       
             [file name]_language_country.[file type]
        
       
      If such a resource exists, return the URL and stop further processing.
    3. Determine if a resource exists with a name constructed as:
       
             [file name]_language.[file type]
        
       
      If such a resource exists, return the URL and stop further processing.
  3. If no localized version of the resource exists, determine if the base resource exists, and if such a resource exists, return the URL and stop further processing.
  4. Return null.

Parameters:
request - the request object from which the preferred locales will be obtained.
Returns:
a new Paje instance.
Throws:
java.io.IOException - if an IO exception occurs.
See Also:
setInternationalisationChecking(boolean)

create

public Paje create(java.lang.String key,
                   java.lang.String[] arguments,
                   javax.servlet.http.HttpServletRequest request)
            throws java.io.IOException
Creates a new localized Paje object from the source file added to this factory by the addResource(java.lang.String, org.pajes.html.PajeResource) method. The source file is mapped to the path after the specified parameters have been substituted into the path pattern, and then the following processing logic is applied to attempt to locate a localized version of the requested resource:
  1. Resolve the base resource name by applying the specified arguments.
  2. Separate the [file name] portion and the [file type] portion of the base resource, using the final period (".") in the path as the delimiter.
  3. For each locale specified on the request, and in preference order:
    1. Determine if a resource exists with a name constructed as:
       
             [file name]_language_country_variant.[file type]
        
       
      If such a resource exists, return the URL and stop further processing.
    2. Determine if a resource exists with a name constructed as:
       
             [file name]_language_country.[file type]
        
       
      If such a resource exists, return the URL and stop further processing.
    3. Determine if a resource exists with a name constructed as:
       
             [file name]_language.[file type]
        
       
      If such a resource exists, return the URL and stop further processing.
  4. If no localized version of the resource exists, determine if the base resource exists, and if such a resource exists, return the URL and stop further processing.
  5. Return null.

Parameters:
key - the key which will uniquely identify this source file.
arguments - the array of arguments that will be substituted into the resource path pattern to give a path to an alternate source file.
request - the request object from which the preferred locales will be obtained.
Returns:
a new Paje instance.
Throws:
java.io.IOException - if an IO exception occurs.
See Also:
setInternationalisationChecking(boolean)

create

public Paje create(java.lang.String[] keys,
                   java.lang.String[] arguments,
                   javax.servlet.http.HttpServletRequest request)
            throws java.io.IOException
Creates a new localized Paje object from the source file added to this factory by the addResource(java.lang.String, org.pajes.html.PajeResource) method. The source file is mapped to the path after the specified parameters have been substituted into the path pattern, and then the following processing logic is applied to attempt to locate a localized version of the requested resource:
  1. For each key in the keys array parameter:
    1. Resolve the base resource name by applying the specified arguments.
    2. Separate the [file name] portion and the [file type] portion of the base resource, using the final period (".") in the path as the delimiter.
    3. For each locale specified on the request, and in preference order:
      1. Determine if a resource exists with a name constructed as:
         
               [file name]_language_country_variant.[file type]
          
         
        If such a resource exists, return the URL and stop further processing.
      2. Determine if a resource exists with a name constructed as:
         
               [file name]_language_country.[file type]
          
         
        If such a resource exists, return the URL and stop further processing.
      3. Determine if a resource exists with a name constructed as:
         
               [file name]_language.[file type]
          
         
        If such a resource exists, return the URL and stop further processing.
  2. If no localized version of any of the requested resources exists, determine if the base resource exists, and if such a resource exists, return the URL and stop further processing.
  3. Return null.

Parameters:
keys - the array of keys which will identify the sequence in which the source file resources will be searched in order to locate the most appropriate match.
arguments - the array of arguments that will be substituted into the resource path pattern to give a path to an alternate source file.
request - the request object from which the preferred locales will be obtained.
Returns:
a new Paje instance.
Throws:
java.io.IOException - if an IO exception occurs.
See Also:
setInternationalisationChecking(boolean)

getPajeResource

public PajeResource getPajeResource(java.lang.String key)
Returns the requested PajeResource.

Parameters:
key - the key under which the resource was added to this factory, or null to retrieve the resource passed to the constructor.
Returns:
the requested PajeResource, or null if it could not be located.

getTemplate

public PajeTemplate getTemplate()
Returns the template object used to generate Pajes.

Returns:
the template object used to generate Pajes.

setDestroyAfterWrite

public void setDestroyAfterWrite(boolean destroy)
Sets the default value for Paje.setDestroyAfterWrite(boolean) for each Paje generated by this factory.

Parameters:
destroy - true if the destroy method should be called, or false if it should not. The default is true.

setFileModificationChecking

public PajeFactory setFileModificationChecking(boolean on)
Determines whether any checks should be made to see if any of the HTML source files managed by this factory have changed.

By default, modification checking is enabled. To change the default, the web application deployment descriptor must have a <context-param> with a <param-name> of org.pajes.html.PajeFactory.fileModificationChecking , and a <param-value> of false. For example:

 
    <context-param>
        <param-name>org.pajes.html.PajeFactory.fileModificationChecking</param-name>
        <param-value>false</param-value>
    </context-param>
  
 

Parameters:
on - if true, the modification date of the source HTML file will be checked to see if it has been changed prior to satisfying the request.
Returns:
the modified Browser.

setInternationalisationChecking

public PajeFactory setInternationalisationChecking(boolean on)
Determines whether any checks should be made to see if an internationalised version of the requested file Paje exists.

By default, internationalisation checking is enabled. To change the default, the web application deployment descriptor must have a <context-param> with a <param-name> of org.pajes.html.PajeFactory.i18nChecking and a <param-value> of false. For example:

 
    <context-param>
        <param-name>org.pajes.html.PajeFactory.i18nChecking</param-name>
        <param-value>false</param-value>
    </context-param>
  
 

Parameters:
on - if true, a check will be made on each request to see if an appropriate internationalised version exists, and if so, return it instead of the default document.
Returns:
the modified Browser.

setTemplate

public void setTemplate(PajeTemplate template)
Sets the template object used to generate Paje objects.

Parameters:
template - the template object used to generate Paje objects.

toString

public java.lang.String toString()
Returns a String representation of this resource.

Overrides:
toString in class java.lang.Object
Returns:
a String representation of this resource.

create

protected Paje create(java.text.MessageFormat keyBase,
                      java.util.Enumeration<?> locales,
                      PajeFactory.Document defaultDocument)
               throws java.io.IOException
Creates a new localized Paje object. See the public create methods for a description of the processing logic.

Sub-classes may over-ride this method to effect changes to every document returned by this factory.

Parameters:
keyBase - a MessageFormat instance that has a single replaceable parameter where the locale string(s) will be inserted.
locales - an Enumeration of Locale objects (in decreasing order starting with the preferred locale). Any non-Locale objects in the Enumeration will be silently ignored. This parameter may be null, in which case the default document will be returned.
defaultDocument - the default document to be used if a localized version cannot be found.
Returns:
a new Paje instance.
Throws:
java.io.IOException - if an IO exception occurs.

find

protected PajeFactory.Document find(java.text.MessageFormat keyBase,
                                    java.util.Enumeration<?> locales,
                                    PajeFactory.Document defaultDocument)
                             throws java.io.IOException
Creates a new localized Paje object. See the public create methods for a description of the processing logic.

Sub-classes may over-ride this method to effect changes to every document returned by this factory.

Parameters:
keyBase - a MessageFormat instance that has a single replaceable parameter where the locale string(s) will be inserted.
locales - an Enumeration of Locale objects (in decreasing order starting with the preferred locale). Any non-Locale objects in the Enumeration will be silently ignored. This parameter may be null, in which case the default document will be returned.
defaultDocument - the default document to be used if a localized version cannot be found.
Returns:
a new Paje instance.
Throws:
java.io.IOException - if an IO exception occurs.

find

protected PajeFactory.Document find(PajeResource resource,
                                    java.lang.String[] arguments)
                             throws java.io.IOException
Finds the PajeFactory.Document object from the source file added to this factory by the addResource(java.lang.String, org.pajes.html.PajeResource) method. If a suitable Document instance cannot be found, one will be created, but only if the target file (after the application of the arguments) can be located.

Parameters:
resource - the PajeResource instance added by the addResource(java.lang.String, org.pajes.html.PajeResource) method.
arguments - the array of arguments that will be substituted into the resource path pattern to give a path to an alternate source file.
Returns:
a Document instance if the path exists, or null if it does not.
Throws:
java.io.IOException - if an IO exception occurs.

find

protected PajeResource find(java.lang.String key)
Finds the base PajeResource object from added to this factory by the addResource(java.lang.String, org.pajes.html.PajeResource) method.

Parameters:
key - the key which will uniquely identify this source file.
Returns:
the PajeResource instance.
Throws:
java.lang.IllegalArgumentException - if the specified key does not exist.

getKeyBase

protected java.text.MessageFormat getKeyBase(PajeResource resource,
                                             java.lang.String[] arguments)
Returns a MessageFormat pattern suitable for creating localized paths.

Parameters:
resource - the resource object. If null, the default localised path will be returned.
arguments - the arguments from which the path can be constructed.
Returns:
the MessageFormat instance.

getServletContext

protected javax.servlet.ServletContext getServletContext()
Returns the servlet context used by this factory.

Returns:
the servlet context.

PAJES 3.0.21

Copyright 1998-2007 Viridian Pty Limited. All Rights Reserved.