eu.bandm.tools.d2d2.base

Class ModuleRegistry

java.lang.Object

eu.bandm.tools.d2d2.base.ModuleRegistry

public final class ModuleRegistry
extends Object

Normally only one central instance exists which resolves module names to Module objects, searching sourceHabitats, like a "ClassLoader" does for Java classes.

For parsing d2d input text, first the doc type definition module is loaded by calling load_instantiated(String).
For some meta-tasks (checking, documentation, visualization) also load_uninstantiated(String) has been made public.
Both rely on a unique mappig of module identifiers to disk files, which contain the module definition text. This can be either (nested!) d2d-definition modules, or third party formats like dtd or umod.
LOCAL module definitions are NOT contained in files of their own, but contained in a certain text document as its prefix. They are inserted in the cache of un-instantiated modules by the text parsing function from Text2Udom EXPLICITLY calling load_local_module(MemScanner,String), and thus retrieved little later by "load_instantiated()", when processing the text header.
Before processing a NEW textfile, the uninstantiated cache must be cleared from all these local modules by calling clearLocalModuleDefs().
For parsing and further processing an INSTANTIATED Module is required. This is calcaluted by Resolver.resolve(Module).
Basic overall control flow is thus as follows:

    load_instantiated(String = module id)
         IFF already found in cache -> return chached instantiated Module object 
                                       (or null in case of former error)
         -> do_load_uninstantiated(String = module id)
                      ->sourceHabitats.searchAllPlaces(id, suffices)
                      ->load_toplevel_module_from_stream()
                           -> XantlrTdom.parse()
                           -> Reducer.reduce()
                           -> Navigate.LocalReferenceNormalizer.match();
         -> Resolver.resolve()
         ELSE load_dtd_module()
                 -> Resolver.resolve()
         ELSE load_umod_module()
                 // MISDING FIXME -> Resolver.resolve()
         // ELSE further formats possible
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	ModuleRegistry.NoSuchSourceFound
protected class	ModuleRegistry.Printer
protected class	ModuleRegistry.PrinterInstantiated
protected class	ModuleRegistry.PrinterUninstantiated

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	cacheChanged
protected File	cacheFile
protected static String[]	D2D_DEF_FILENAME_EXTENSIONS List of file suffices tested for module definitions.
protected Map<String,Module>	instantiated
protected @Opt ResolvedModule	loadedMetaModule
protected boolean	metaModuleLoaded
protected MessageReceiver<SimpleMessage<XMLDocumentIdentifier>>	msg
static String	sourceHabitatErrorHint
protected SourceHabitats	sourceHabitats Mangages all file system locations / http locations / jar resources etc.
protected Map<String,Module>	toplevel_uninstantiated
protected int	tracelevel
boolean	useResolver34
protected Map<Module,Map<String,eu.bandm.tools.d2d2.base.ModuleRegistry.XsltLoaded>>	xslt_loaded

Constructor Summary

Constructors

Constructor and Description
ModuleRegistry(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg, boolean useResolver34)

Method Summary

Modifier and Type	Method and Description
void	appendToSourceList(String s) Appends a string which is the representation of a possible location of module sources to the END of the list of searched locations, as maintained by sourceHabitats.
void	clearLocalModuleDefs()
protected @Opt Module	do_load_uninstantiated(String modpath) Loads a d2d definition module, from top or non-top level.
protected void	ERROR(Exception ex, Location<XMLDocumentIdentifier> loc, String txt)
protected void	ERROR(String txt)
protected void	ERROR(String txt, Exception ex)
protected String	fileSuffices_toString()
static SourceLocator	getRootSourceLocator(Throwable exception) Published routine from the xalan project page, http://xalan.apache.org/old/xalan-j/faq.html#faq-N103D5
void	initCache(File f) Opens the file, iff it exists, and reads its contents into a map.
protected @Opt Module	load_dtd_module(String s) Looks in all sourceHabitats for a "[s].dtd" file, parses the found file and converts it into a d2d definition module, which is stored under the name "s" as an instantiated module.
@Opt Module	load_instantiated(String s) Loads a module identified by its name (a sequence of identifiers separated by Chars.REGEXP_NAMING_LEVEL_SEPARATOR) and subsequently instantiates all imports etc.
protected @Opt Module	load_local_module(MemScanner mem, String filename) Feed the prefix of a text document into the cache of uninstantiated modules, to retrieve it instantiated (a few steps later).
protected @Opt Module	load_toplevel_module_from_reader(Reader charstream, String filename, boolean local) Loads a top-level d2d definition module (with all sub-modules, uninstantiaated), which has not yet been read in at all. Is called (internally) for a top-level module, which (together with its sub-modules contained therein) makes up the whole stream content, --- or externally for local modules, which start at the current stream reading position.
protected @Opt Module	load_toplevel_module_from_stream(InputStream stream, String filename, boolean local) Only converts the byte source to a character source, assuming utf-8 encoding.
protected @Opt Module	load_umod_module(String s) Looks in all sourceHabitats for a "[s].umod" file, parses the found file and converts it into a d2d definition module, which is stored under the name "s" as an instantiated module.
@Opt Module	load_uninstantiated(String s) External entry point for loading an uninstantiated, unchecked (GLOBAL!) d2d module, but only iff it exists in the genuine d2d-definition format ".df2"/".ddf".
protected @Opt ResolvedModule	loadMetaModule() Returns null in case of error.
@Opt Templates	loadXslt(Module sourceModule, String targetModule, @Opt String targetTopTag) Loads the xslt definitions coming with the d2d module definitions.
protected void	LOG(String txt)
protected void	LOGEND(String txt)
protected void	LOGSTART(String txt)
static ModuleRegistry	makeInstance(@Opt String[] searchpath, MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msgr, int debug)
static ModuleRegistry	makeInstance(@Opt String[] searchpath, MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msgr, int debug, boolean useResolver3) Wrapper which creates and initializes.
protected void	markCacheChanged()
void	print_instantiated(String name, PrintStream p, int w)
void	print_uninstantiated(String name, PrintStream p, int w)
void	saveCache() Write all parsed module definitions als xslt Templates into the cache file, iff one has been set by calling initCache(File).
protected void	sendFileNotFoundErrorMsg(String modname, boolean includealternatives)
void	setMsgReceiver(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg)
void	setTracelevel(int tracelevel)
void	trace(int level, String txt)
protected void	trace(int level, String txt, Object... obj)
protected boolean	transformerException2errorMessage(Throwable ex, LocationMap<XMLDocumentIdentifier,XMLDocumentIdentifier> stringpos2filepos) ATTENTION pure heuristics WHERE to find the error diagnosis !?!?! Returns true iff an error message could be created.
protected void	WARNING(String txt)

Methods inherited from class java.lang.Object

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

Field Detail

sourceHabitatErrorHint

public static final String sourceHabitatErrorHint

See Also:

Constant Field Values

useResolver34

public boolean useResolver34

msg

protected MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg

tracelevel

protected int tracelevel

toplevel_uninstantiated

protected Map<String,Module> toplevel_uninstantiated

instantiated

protected Map<String,Module> instantiated

sourceHabitats

protected SourceHabitats sourceHabitats

Mangages all file system locations / http locations / jar resources etc. which are potential places for module source text.

cacheFile

protected File cacheFile

cacheChanged

protected boolean cacheChanged

D2D_DEF_FILENAME_EXTENSIONS

protected static final String[] D2D_DEF_FILENAME_EXTENSIONS

List of file suffices tested for module definitions. FIXME make it configurable!

metaModuleLoaded

protected boolean metaModuleLoaded

loadedMetaModule

@Opt
protected @Opt ResolvedModule loadedMetaModule

xslt_loaded

protected Map<Module,Map<String,eu.bandm.tools.d2d2.base.ModuleRegistry.XsltLoaded>> xslt_loaded

Constructor Detail

ModuleRegistry

public ModuleRegistry(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg,
                      boolean useResolver34)

Method Detail

setTracelevel

public void setTracelevel(int tracelevel)

appendToSourceList

public void appendToSourceList(String s)

Appends a string which is the representation of a possible location of module sources to the END of the list of searched locations, as maintained by sourceHabitats.

markCacheChanged

protected void markCacheChanged()

initCache

public void initCache(File f)

Opens the file, iff it exists, and reads its contents into a map. Otherwise it will be created later, in saveCache().

saveCache

public void saveCache()

Write all parsed module definitions als xslt Templates into the cache file, iff one has been set by calling initCache(File).

clearLocalModuleDefs

public void clearLocalModuleDefs()

setMsgReceiver

public void setMsgReceiver(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg)

makeInstance

public static ModuleRegistry makeInstance(@Opt
                                          @Opt String[] searchpath,
                                          MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msgr,
                                          int debug)

makeInstance

public static ModuleRegistry makeInstance(@Opt
                                          @Opt String[] searchpath,
                                          MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msgr,
                                          int debug,
                                          boolean useResolver3)

Wrapper which creates and initializes.

fileSuffices_toString

protected String fileSuffices_toString()

trace

public void trace(int level,
                  String txt)

trace

protected void trace(int level,
                     String txt,
                     Object... obj)

WARNING

protected void WARNING(String txt)

ERROR

protected void ERROR(String txt)

ERROR

protected void ERROR(String txt,
                     Exception ex)

ERROR

protected void ERROR(Exception ex,
                     Location<XMLDocumentIdentifier> loc,
                     String txt)

LOG

protected void LOG(String txt)

LOGSTART

protected void LOGSTART(String txt)

LOGEND

protected void LOGEND(String txt)

sendFileNotFoundErrorMsg

protected void sendFileNotFoundErrorMsg(String modname,
                                        boolean includealternatives)

load_instantiated

@Opt
public @Opt Module load_instantiated(String s)

Loads a module identified by its name (a sequence of identifiers separated by Chars.REGEXP_NAMING_LEVEL_SEPARATOR) and subsequently instantiates all imports etc.
Try module name as d2d definition, afterwards as dtd or umod, etc.

All non-local modules will be saved for future retrieval.
Eg look first for all places in sourceHabitats, whether there is a "ddf", and then look again in sourceHabitats for a "umod" or "dtd".

FIXME: This is a strategy deciding method, so it should be pluggable !?!?
Alternatives:
Treat ".ddf", ".umod" and ".dtd" with same priority.
Or -- treat dtd with highest priority, then "ddf" and "umod".
etc.
Can not be used recursively.

Returns:

null when errors occured in loading an existing source file, or when no single source file variant is visible.

load_uninstantiated

@Opt
public @Opt Module load_uninstantiated(String s)

External entry point for loading an uninstantiated, unchecked (GLOBAL!) d2d module, but only iff it exists in the genuine d2d-definition format ".df2"/".ddf". The module is identified by its name (a sequence of identifiers separated by Chars.REGEXP_NAMING_LEVEL_SEPARATOR). May be called eg. for documentation generation. Sends log and error messages to msg and returns null on failure, including file-not-found.

load_dtd_module

@Opt
protected @Opt Module load_dtd_module(String s)
                                    throws ModuleRegistry.NoSuchSourceFound

Looks in all sourceHabitats for a "[s].dtd" file, parses the found file and converts it into a d2d definition module, which is stored under the name "s" as an instantiated module. returns "null" in case of error and sends error messages to GLO IN msg. But throws ModuleRegistry.NoSuchSourceFound when no file is visible, to let the caller test an alternative.

Throws:

ModuleRegistry.NoSuchSourceFound

loadMetaModule

@Opt
protected @Opt ResolvedModule loadMetaModule()

Returns null in case of error.

load_umod_module

@Opt
protected @Opt Module load_umod_module(String s)
                                     throws ModuleRegistry.NoSuchSourceFound

Looks in all sourceHabitats for a "[s].umod" file, parses the found file and converts it into a d2d definition module, which is stored under the name "s" as an instantiated module. returns "null" in case of error and sends error messages to GLO IN msg. But throws ModuleRegistry.NoSuchSourceFound when no file is visible, to let the caller test an alternative.

Throws:

ModuleRegistry.NoSuchSourceFound

do_load_uninstantiated

@Opt
protected @Opt Module do_load_uninstantiated(String modpath)
                                           throws ModuleRegistry.NoSuchSourceFound

Loads a d2d definition module, from top or non-top level. Read toplevel module either from cache, or try to get it from external media. This is an internal version, called by load_instantiated(String) and load_uninstantiated(String).

Returns:

null on error (and send error messages to receiver!)

Throws:

{@link - NoSuchSourceFound} iff no file can be located

ModuleRegistry.NoSuchSourceFound

load_local_module

@Opt
protected @Opt Module load_local_module(MemScanner mem,
                                             String filename)

Feed the prefix of a text document into the cache of uninstantiated modules, to retrieve it instantiated (a few steps later). Returns null in case of errors.

load_toplevel_module_from_stream

@Opt
protected @Opt Module load_toplevel_module_from_stream(InputStream stream,
                                                            String filename,
                                                            boolean local)

Only converts the byte source to a character source, assuming utf-8 encoding. Returns null in case of errors.

load_toplevel_module_from_reader

@Opt
protected @Opt Module load_toplevel_module_from_reader(Reader charstream,
                                                            String filename,
                                                            boolean local)

Loads a top-level d2d definition module (with all sub-modules, uninstantiaated), which has not yet been read in at all.

Is called (internally) for a top-level module, which (together with its sub-modules contained therein) makes up the whole stream content, --- or externally for local modules, which start at the current stream reading position.
The module(s) is(/are) put into toplevel_uninstantiated, and retrieved from there when resolving the (subsequent) document type decl, cf. Text2Udom.scanForHeader().

Returns:

{code null} on error (and send error messages to receiver!)

loadXslt

@Opt
public @Opt Templates loadXslt(Module sourceModule,
                                    String targetModule,
                                    @Opt
                                    @Opt String targetTopTag)

Loads the xslt definitions coming with the d2d module definitions. Uses the cache map xslt_loaded, ie. tries to parse and compile a certain stylesheet only once in each run of this program. This mainly because called by "Main.udom2xslt2document", which is used by "Ddf2Doc" for rendering the docu texts into xhtml.
This current version uses the JAXP interface (which normally is a built-in Xalan). For using our own Txsl, the phases of (1) extracting d2d, (2) converting it to xml-encoded xslt and (3) building up the data structure must be untangled. FIXME MISSING

Parameters:

sourceModule - the 2d module which defines the transformation sources

targetModule - name of the target module as it appears in the key of the transformation rule, eg. "xhtml_1_0" in "to_xhtml_1_0"

targetTopTag - tag of the result. This is required because the d2d-special-format for xslt rules interleaves parsing of xslt-syntax and of the target syntax. For the latter, a preparational step collects all open-tags reachable from this "top-level" element.

transformerException2errorMessage

protected boolean transformerException2errorMessage(Throwable ex,
                                                    LocationMap<XMLDocumentIdentifier,XMLDocumentIdentifier> stringpos2filepos)

ATTENTION pure heuristics WHERE to find the error diagnosis !?!?! Returns true iff an error message could be created.

getRootSourceLocator

public static SourceLocator getRootSourceLocator(Throwable exception)

Published routine from the xalan project page, http://xalan.apache.org/old/xalan-j/faq.html#faq-N103D5

print_instantiated

public void print_instantiated(String name,
                               PrintStream p,
                               int w)

print_uninstantiated

public void print_uninstantiated(String name,
                                 PrintStream p,
                                 int w)