org.enhydra.xml.xmlc.deferredparsing
Class XMLCDeferredParsingFactory

java.lang.Object
  |
  +--org.enhydra.xml.xmlc.XMLCStdFactory
        |
        +--org.enhydra.xml.xmlc.deferredparsing.XMLCDeferredParsingFactory
All Implemented Interfaces:
XMLCFactory

public class XMLCDeferredParsingFactory
extends XMLCStdFactory

Factory class to create instances of an XMLC-generated class with "deferred parsing". Deferred parsing means that the DOM is parsed from a file on first access and re-parsed on subsequent accesses whenever the DOM is out of date with regard to the source file.


Constructor Summary
XMLCDeferredParsingFactory(DocumentLoader docLoader, ClassLoader classLoader, XMLCLogger logger)
           
 
Method Summary
 void addPackagePrefix(String prefix)
           
 void addResourceDir(String path)
           
 XMLObject create(XMLCCreateOptions xmlcCreateOptions)
          Creates an instance of an XMLC-generated class, or a class derived from one, using the associated classloader, given one of the following...
 XMLObject createFromFile(String filename)
          Deprecated. use #create(XMLCCreateOptions) instead
 XMLObject createFromFile(String filename, String domFactoryClassName)
          Deprecated. use #create(XMLCCreateOptions) instead
protected  XMLObject doCreate(Class xmlcBasedClass)
          Create a new document instance.
protected  XMLObject doCreate(String xmlcClassName, ClassLoader classLoader)
          Do the actual work of creating a new object given a name.
static Object getClassConstant(Class xmlcBasedClass, String constName)
          Get one of the compiled-in constants in a XMLC-generated class (or subclass).
 String getDefaultMetaDataFile()
           
 URL getDefaultMetaDataURL()
           
 Locale[] getLocales()
          Meant to provide the DocumentLoader instance, associated with the current instance of this class, access to user-defined Locale objects (user and developer-preferred fallback) for use in loading localized markup files.
(package private)  List getPackagePrefixList()
           
 String[] getPathsFromPackagePrefixes(String path)
          Get possible file paths by subtracting each respective package prefix from the path prefix.
 URL getPathURLFromClasspath(String path)
           
 URL getPathURLFromResourceDir(String path)
           
(package private)  List getResourceDirList()
           
static String getSourceFilePath(Class docClass)
          Get the name of the source file associated with docClass
static String getXmlcClassMetaDataFilePath(Class xmlcClass)
           
 String[] getXmlcClassMetaDataFilePaths(Class docClass)
          Get the metadata file paths.
 String[] getXmlcSourceMetaDataFilePaths(String xmlcSourceFilePath)
          Get the metadata file paths.
 boolean isEnableI18n()
           
 MetaData loadMetaData(URL metaDataURL, ErrorReporter errorReporter)
           
 void remove(String prefix)
          Deprecated.  
 void removePackagePrefix(String prefix)
           
 void removeResourceDir(String path)
           
 void setDefaultFallbackLocale(Locale defaultFallbackLocale)
           
 void setDefaultMetaDataPath(String path)
           
 void setEnableI18n(boolean enableI18n)
          Set the flag to enable Internationalization (I18n), or Localization (L10n).
 
Methods inherited from class org.enhydra.xml.xmlc.XMLCStdFactory
create, create, getDefaultClassLoader, getLogger, handleError
 
Methods inherited from class java.lang.Object
, clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XMLCDeferredParsingFactory

public XMLCDeferredParsingFactory(DocumentLoader docLoader,
                                  ClassLoader classLoader,
                                  XMLCLogger logger)
Parameters:
docLoader - Document loader to use or null
classLoader - Classloader used to load classes when a class name is specified. If null, the system classload is used. for the StandardDocumentLoader
logger - XMLC logger or null for no logging.
Method Detail

doCreate

protected XMLObject doCreate(Class xmlcBasedClass)
                      throws ClassNotFoundException,
                             IllegalAccessException,
                             InstantiationException
Create a new document instance.
Overrides:
doCreate in class XMLCStdFactory

doCreate

protected XMLObject doCreate(String xmlcClassName,
                             ClassLoader classLoader)
                      throws ClassNotFoundException,
                             IllegalAccessException,
                             InstantiationException
Do the actual work of creating a new object given a name.
Overrides:
doCreate in class XMLCStdFactory

create

public XMLObject create(XMLCCreateOptions xmlcCreateOptions)
Creates an instance of an XMLC-generated class, or a class derived from one, using the associated classloader, given one of the following...
  1. xmlcClass (implementation or interface)
  2. xmlcClassName (implementation or interface)
  3. dynMarkupFilePath

When using dynamic loading, one may define the optional dynDomFactoryClassName , define it in the default metadata, or just fall back to the XMLCDomFactoryCache class default, in that order.

The optional user and fallback Locales are utilized in choosing the markup file associated with the class. Locale-named markup files, if found, are used in preference to the base markup file. If the user Locale is null, the fallback Locale is used in its place. If the fallback Locale is null, the defaultFallbackLocale is used in its place (as well as the user Locale if it is also null).

Markup files are looked up based first on user Locale and, if not found, then on fallback Locale and, if not found, finally the base markup file is used.

Note that the Locales are ignored if isEnableI18n() returns false or the Locales are null.

Parameters:
xmlcCreateOptions - the XMLC create options providing information on how to load the XMLObject
Returns:
an XMLObject document instance
Since:
2.3.2
See Also:
setEnableI18n(boolean), setDefaultFallbackLocale(java.util.Locale)

createFromFile

public XMLObject createFromFile(String filename)
Deprecated. use #create(XMLCCreateOptions) instead

See Also:
createFromFile(String, String), create(XMLCCreateOptions)

createFromFile

public XMLObject createFromFile(String filename,
                                String domFactoryClassName)
Deprecated. use #create(XMLCCreateOptions) instead

Same as create(new XMLCCreateOptions().setMarkupFilePath(filename).setDomFactoryClassName(domFactoryClassName))
See Also:
create(XMLCCreateOptions)

addResourceDir

public void addResourceDir(String path)
Parameters:
path - a path to add as a resource directory

removeResourceDir

public void removeResourceDir(String path)
Parameters:
path - a path to remove as a resource directory

getResourceDirList

List getResourceDirList()
Returns:
the resource directory list

addPackagePrefix

public void addPackagePrefix(String prefix)
Parameters:
prefix - a package prefix to add

removePackagePrefix

public void removePackagePrefix(String prefix)
Parameters:
prefix - a package prefix to remove
Since:
2.3.2

remove

public void remove(String prefix)
Deprecated.  

Parameters:
prefix - a package prefix to remove
See Also:
removePackagePrefix(java.lang.String)

getPackagePrefixList

List getPackagePrefixList()
Returns:
the package prefix list, the list of package prefixes is separated with File.pathSeparator instead of '.'

setDefaultMetaDataPath

public void setDefaultMetaDataPath(String path)
Parameters:
path - the path to the meta data file

getDefaultMetaDataFile

public String getDefaultMetaDataFile()
Returns:
the default meta data file to be used by the dynamically added pages

isEnableI18n

public final boolean isEnableI18n()
Returns:
true if I18n is enabled, false if disabled
Since:
2.3.2
See Also:
setEnableI18n(boolean)

setEnableI18n

public final void setEnableI18n(boolean enableI18n)
Set the flag to enable Internationalization (I18n), or Localization (L10n). When true, extra lookups are performed for markup files named in a way to mimick ResourceBundle functionality. By default, this is false to avoid incurring a performance impact when such functionality is not needed nor desired.

Note it's capital "I", and it's "I18n", not "Il8n" (Number "1", not letter "l"). See http://www.i18nguy.com/origini18n.html

Parameters:
enableI18n - true to enable, false to disable (default)
Since:
2.3.2
See Also:
getLocales()

setDefaultFallbackLocale

public final void setDefaultFallbackLocale(Locale defaultFallbackLocale)
Parameters:
defaultFallbackLocale - the default fallback Locale, used in the case where I18n is enabled and no fallbackLocale (or user locale) is specified on the create(XMLCCreateOptions) method.
Since:
2.3.2
See Also:
setEnableI18n(boolean)

getLocales

public final Locale[] getLocales()
Meant to provide the DocumentLoader instance, associated with the current instance of this class, access to user-defined Locale objects (user and developer-preferred fallback) for use in loading localized markup files.

Note that this method is guaranteed to return null unless setEnableI18n(true) is called.

Note also that the value returned by this method is time/unit-of-work context dependent on a per/thread basis. The value will be null when called out of context or even when in context but no non-null user-defined Locales are provided. As such, take care to check for null prior to using the returned value and, of course, don't cache it either.

Returns:
the user-defined Locales ([0] == locale, [1] == fallbackLocale), available for the duration of calls to create(XMLCCreateOptions) invocation on a per/thread thread basis.
Since:
2.3.2
See Also:
setEnableI18n(boolean), setDefaultFallbackLocale(java.util.Locale)

loadMetaData

public final MetaData loadMetaData(URL metaDataURL,
                                   ErrorReporter errorReporter)
                            throws XMLCException
Parameters:
metaDataURL - the URL of the metadata file
errorReporter - used to report metadata parse errors
Returns:
the metadata represented by the URL
Throws:
XMLCException - if something goes wrong loading metadata
Since:
2.3.2

getDefaultMetaDataURL

public final URL getDefaultMetaDataURL()
Returns:
the default metadata URL, accounting for configured package prefixes, with dots normalized to forward slashes and looked up by the configured document loader implementation
Since:
2.3.2
See Also:
getDefaultMetaDataFile(), getPathsFromPackagePrefixes(String)

getXmlcClassMetaDataFilePaths

public final String[] getXmlcClassMetaDataFilePaths(Class docClass)
Get the metadata file paths. Provides an array containing possible paths to an XMLC class metadata file including every combination of paths corresponding to configured package prefixes. Paths represent metadata files for both interface and "Impl" classes as well as source files. This covers all cases of XMLC metadata file generation.

An ascending sort is applied resulting in a consistent order when dealing with configured package prefix paths and interface -vs- "Impl" extensions.

Parameters:
xmlcClassMetaDataFilePath - a relative path (no leading slash) to the meta data file for an XMLC class
Returns:
a sorted array of possible paths to an XMLC class metadata file accounting for interface and Impl classes, both within configured package prefixes
Since:
2.3.2
See Also:
getXmlcClassMetaDataFilePath(Class), getXmlcSourceMetaDataFilePaths(String), getPathsFromPackagePrefixes(String)

getXmlcSourceMetaDataFilePaths

public final String[] getXmlcSourceMetaDataFilePaths(String xmlcSourceFilePath)
Get the metadata file paths. Provides an array containing possible paths to an XMLC source (as opposed to class) metadata file including every combination of paths corresponding to configured package prefixes.
Parameters:
xmlcSourceFilePath - a relative path (no leading slash) to a source markup file
Returns:
an array of possible paths to an XMLC source metadata file, corresponding to the provided xmlcSourceFilePath, accounting for configured package prefixes
Since:
2.3.2
See Also:
getPathsFromPackagePrefixes(String)

getClassConstant

public static Object getClassConstant(Class xmlcBasedClass,
                                      String constName)
Get one of the compiled-in constants in a XMLC-generated class (or subclass).
Since:
2.3.2

getSourceFilePath

public static String getSourceFilePath(Class docClass)
                                throws XMLCRuntimeException
Get the name of the source file associated with docClass
Since:
2.3.2

getPathsFromPackagePrefixes

public final String[] getPathsFromPackagePrefixes(String path)
Get possible file paths by subtracting each respective package prefix from the path prefix. The original path is included last in the returned value. Both locale and fallbackLocale are accounted for in the paths except when the path represents an XMLC metadata file.
Parameters:
path - a relative path (no leading slash) to either a source markup file or XMLC metadata file
Returns:
an array of possible paths to a file, accounting for configured package prefixes
Since:
2.3.2

getPathURLFromResourceDir

public final URL getPathURLFromResourceDir(String path)
Parameters:
path - the relative path to the source file
Returns:
the URL for a path relative to a configured resource dir
Since:
2.3.2

getPathURLFromClasspath

public final URL getPathURLFromClasspath(String path)
Parameters:
path - the fully qualified path to the source file (with no leading slashes)
Returns:
the URL for a path relative to the classpath
Since:
2.3.2

getXmlcClassMetaDataFilePath

public static String getXmlcClassMetaDataFilePath(Class xmlcClass)
Parameters:
xmlcClass - an XMLC class
Returns:
a path corresponding to to the FQCN of the provided XMLC class, with periods replaced by slashes and ".class" replaced by ".xmlc", representing the metadata path (less the "Impl" extension if it exists)
Since:
2.3.2


Copyright © 1999-2007 enhydra.org (Mark Diekhans, David Li, Richard Kunze, Jacob Kjome). All Rights reserved.