Package eu.bandm.tools.d2d2.base

Class Tasks

java.lang.Object

eu.bandm.tools.d2d2.base.Tasks

public class Tasks
extends Object

Collection of static methods which realize the different d2d conversion tasks. These are the currently supported PIPELINES (implemented mostly here and in partly in Main):

 textfile ---> udom ----------------> sax ----> xml textfile         (1)
                                           \
                                             -> tdom                 (2)

 textfile ---> udom --sax--[xslt]---> sax --> textfile (xml/no-xml)  (3) 
                             ^              \
                             |                -> tdom                (4)
                             \________________________________
                                                              \
                                                       -->Txsl Code (=own implementation,
                                                     /              ( formerly: JAXP translet
 modulereg ---> xslt-d2d-source                     / 
                xslt-d2d-source--------> udom --> sax --> xml xslt source (5)
                   \         (text2xml parser)            
                    \        (  in xslt mode )                           
                     \----------------------------------> d2d xslt source (5)

 (MODULE.{ddf,umod,dtd, etc.}
    \
     V
    modulereg ------------------------------------------> MODULE.dtd       (6)
          \ 
           \ -------------------------------------------> FILENAME.ddf     (7)
            \ 
             \ ------------> d2d_documentation_{stat/inst}_[MODULE]_[LANG] (8) 
              \ 
               \ ---------------------------------------> FILENAME.html    (9)
                \ 
                 \ -------------------------------------> FILENAME.xml     (10)

 
 MODULE.dtd --------------------------------------------> MODULE.ddf       (11)
 

Legend:

(1) Main use case: produce an XML output file from a d2d input text file in "one-to-one" discipline.
Initiated from commandline by "Main --task text2xml".
Initiated programmatically by calling #text2xml(MessageReceiver, ModuleRegistry, Text2Udom.ErrorStrategy, File, String, ContentHandler, File)

(2) Main use case: produce a TDOM model from a d2d text in "one-to-one" discipline.
Initiated programmatically by calling (File, ModuleRegistry, Class, TypedDTD, MessageReceiver, Text2Udom.ErrorStrategy, int)

(3) and (4): Derived use case: produce output file (xml/non-xml) or tdom model by first translating a d2d text file to xml, as in (1), and then applying xslt transformations into specified target formats. Not longer implemented here, use Batch instead.

(5) Auxiliary use case: write out the xslt transformation for a given module and a given target format.
Initiated from commandline by "Main --task ddf2xslt"; implemented in ddf2xslt(eu.bandm.tools.message.MessageReceiver<eu.bandm.tools.message.SimpleMessage<eu.bandm.tools.util.xml.XMLDocumentIdentifier>>, int, eu.bandm.tools.d2d2.base.ModuleRegistry, java.lang.Iterable<java.lang.String>, java.lang.String, java.lang.String, java.lang.String, java.lang.String, eu.bandm.tools.d2d2.base.Text2Udom.ErrorStrategy, java.lang.String, int). (6) Auxiliary use case: translate the ddf definition of a given module into a DTD.
Initiated from commandline by "Main --task ddf2dtd"; implemented in Def2Dtd.convert(MessageReceiver, Module, XMLDocumentIdentifier, boolean, String).

(7) Auxiliary use case: pretty-print the ddf definition of a given module.
Initiated from commandline by "Main --task ddf2format"; implemented by the format rules in the umod definition.

(8) Auxiliary use case: generate HTML formatted user documentation for a given module in a given state (raw or instantiated) in a given human language.
Initiated from commandline by "Main --task ddf2doc"; implemented in UserdocUninstantiated and UserdocInstantiated.

(9) Auxiliary use case: translate the ddf definition of a given module into a html formular with labels and input fields.
Initiated from commandline by "Main --task ddf2htmlform"; (currently not supported, old implementation in OLD ../../d2d/base/Def2HtmlForm.)

(10) Auxiliary use case: write out a given module in umod tsoap xml format.
Initiated from commandline by "Main --task ddf2tsoap";

(11) Auxiliary use case: write out the ddf equivalent of a dtd
Initiated from commandline by "Main --task dtd2ddf";
Implemented in Dtd2Def, which is also called by Modulereg, when a dtd is used as ddf. But the use case is slightly different from (7), since more errors must be signalled explicitly and more diagnosis is required.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
(package private) static class	Tasks.XsltExtractionResult	Keeps the results of extracting one particular xslt program.

Method Summary

Modifier and Type	Method	Description
static String	ddf2doc3(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg, int tracelevel, ModuleRegistry moduleReg, String modulename, String language, boolean isStatic, String outputname, String gencomment, @Opt NamespaceName2String ext_stylesheetParams, @Opt Iterable<String> additionalSources, int lineWidth)	Service point: Generate the HTML documentation for a given module, ie.
static void	ddf2dtd(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg, ModuleRegistry moduleReg, String modulename, String docuLanguage, String fileOutputName, int lineWidth)	Service point: Convert a d2d module definition to a dtd file.
static void	ddf2xslt(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg, int verbosity, ModuleRegistry moduleReg, @Opt Iterable<String> additionalSources, String modulename, String targetModule, @Opt String targetTopTag, String outputname, Text2Udom.ErrorStrategy errorStrategy, String genString, int lineWidth)	Service point: Extracts all xslt rules for the given module and target into a d2d definition and exports this to two xslt source files, in d2d and in xml encoding.
static void	ddf2xslt(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg, int verbosity, ModuleRegistry moduleReg, @Opt Iterable<String> additionalSources, String modulename, String targetModule, @Opt String targetTopTag, String outputname, Text2Udom.ErrorStrategy errorStrategy, String genString, int lineWidth, boolean writeAdditionallyToXmlFile)	Service point: Extracts all xslt rules for the given module and target into a d2d definition and exports this to a d2d source file.
protected static void	e_error(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg, Exception ex, String s, Object... args)	Evident
protected static void	e_error(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg, String s, Object... args)	Evident
protected static void	e_log(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg, String s, Object... args)	Evident
protected static void	e_logEnd(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg, String s)	Evident
protected static void	e_logStart(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg, String s, Object... args)	Evident
static @Opt Tasks.XsltExtractionResult	get_xslt_xml(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg, int tracelevel, Trace xsltTrace, ModuleRegistry moduleRegistry, Text2Udom.ErrorStrategy errorStrategy, ResolvedModule mod, String key, ResultContext resultContext, String topElementName, LocationMap<XMLDocumentIdentifier,XMLDocumentIdentifier> stringpos2filepos, boolean writeIntermediateXsltCodeToFile, @Opt String dateNow, @Opt String fileBasis, int lineWidth)	Because it is very unlikely that the same xslt source text must be processed by both Txsl and Jre-xslt, no cache is maintained for the intermediate Udom result, which in that rare case must be calculated twice.
static @Opt Location<XMLDocumentIdentifier>	getRootSourceLocator(Throwable exception)	Follows a published routine from the xalan project page, http://xalan.apache.org/old/xalan-j/faq.html#faq-N103D5
static Transformation	getTransformation(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg, int tracelevel, Trace xsltTrace, ModuleRegistry moduleRegistry, Text2Udom.ErrorStrategy errorStrategy, ResolvedModule mod, String key, ResultContext resultContext, String topElementName, TransformationCache transformationsCache, Transformation.Modifiers txsl_modifiers, FunctionLibrary<?> functionLibrary, LocationMap<XMLDocumentIdentifier,XMLDocumentIdentifier> stringpos2filepos, boolean writeIntermediateXsltCodeToFile, @Opt String dateNow, @Opt String fileBasis, int lineWidth)	Service point: Deliver the xslt Transformation object for given source and target formats.
static Templates	getTransformation_jre(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg, int tracelevel, Trace xsltTrace, ModuleRegistry moduleRegistry, Text2Udom.ErrorStrategy errorStrategy, ResolvedModule mod, String key, ResultContext resultContext, String topElementName, TransformationCache transformationsCache, Transformation.Modifiers txsl_modifiers, FunctionLibrary<?> functionLibrary, LocationMap<XMLDocumentIdentifier,XMLDocumentIdentifier> stringpos2filepos, boolean writeIntermediateXsltCodeToFile, @Opt String dateNow, @Opt String fileBasis, int lineWidth)
static <T extends TypedDocument, D extends TypedDTD> T	string2tdom(String sourcetext, ModuleRegistry modreg, Class<T> documentClass, D dtdInstance, MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msgr, Text2Udom.ErrorStrategy errorStrategy, int debug)	Convert a d2d source text into a tdom model.
static <T extends TypedDocument, D extends TypedDTD> T	text2tdom(@Opt File infile, ModuleRegistry modreg, Class<T> documentClass, D dtdInstance, MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msgr, Text2Udom.ErrorStrategy errorStrategy, int debug)	Service point: Convert a d2d input file into a tdom model.
static void	text2xml(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> e_msg, int debuglevel, ModuleRegistry e_moduleReg, Text2Udom.ErrorStrategy errorStrategy, File e_sourcefile, Charset encoding, @Opt String generationComment, @Opt ContentHandler contentHandler, @Opt File xmlfile)	Service point: Convert directly a d2d encoded input text file into xml, either to a file or to a programmed consumer or to both.
static void	text2xml(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> e_msg, int debuglevel, ModuleRegistry e_moduleReg, Text2Udom.ErrorStrategy errorStrategy, Reader e_source, @Opt String sourceIndication, @Opt String generationComment, @Opt ContentHandler contentHandler, @Opt File xmlfile)	Service point: Convert directly a d2d encoded text from a Reader into xml, either to a file or to a programmed consumer or to both.
static boolean	transformerException2errorMessage(Throwable ex, MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg, @Opt LocationMap<XMLDocumentIdentifier,XMLDocumentIdentifier> stringpos2filepos)	ATTENTION pure heuristics WHERE to find the error diagnosis !?!?!
(package private) static Location<XMLDocumentIdentifier>	x_location(@Opt String pub, String sys, int lin, int col)	Make a location with the given coordinates.

Methods inherited from class java.lang.Object

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

Method Details

e_log

protected static void e_log(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg,
 String s,
 Object... args)

Evident

e_logStart

protected static void e_logStart(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg,
 String s,
 Object... args)

Evident

e_logEnd

protected static void e_logEnd(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg,
 String s)

Evident

e_error

protected static void e_error(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg,
 String s,
 Object... args)

Evident

e_error

protected static void e_error(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg,
 Exception ex,
 String s,
 Object... args)

Evident

ddf2dtd

public static void ddf2dtd(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg,
 ModuleRegistry moduleReg,
 String modulename,
 String docuLanguage,
 String fileOutputName,
 int lineWidth)

Service point: Convert a d2d module definition to a dtd file.

getTransformation

public static Transformation getTransformation(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg,
 int tracelevel,
 Trace xsltTrace,
 ModuleRegistry moduleRegistry,
 Text2Udom.ErrorStrategy errorStrategy,
 ResolvedModule mod,
 String key,
 ResultContext resultContext,
 String topElementName,
 TransformationCache transformationsCache,
 Transformation.Modifiers txsl_modifiers,
 FunctionLibrary<?> functionLibrary,
 LocationMap<XMLDocumentIdentifier,XMLDocumentIdentifier> stringpos2filepos,
 boolean writeIntermediateXsltCodeToFile,
 @Opt
 @Opt String dateNow,
 @Opt
 @Opt String fileBasis,
 int lineWidth)

Service point: Deliver the xslt Transformation object for given source and target formats. Extract the source text of the xslt rules from the module definition and parse it to an immediately executable xslt code object.

Parameters:

msg - receiver for all log and error messages

tracelevel - level of verbositiy, see the documentation of ModuleRegistry.setTracelevel(int).

xsltTrace - control object for xslt tracing and debugging

moduleRegistry - to load the modules "d2d2-meta" and "xslt".

errorStrategy - controls d2d parsing process

mod - resolved module containing the definition of the top-most element to translate

key - the label in the ddf text which selects the transfomation rules for extraction

resultContext - gives target tdom class und cached properties of the target language

topElementName - the name on the OUTPUT side to find all reachable definitions

transformationsCache - cache for all loaded xslt transformations

txsl_modifiers - controls xslt execution and error checking

functionLibrary - used by xpath

stringpos2filepos - an output parameter: a map where the extraction algorithm can enter the relation from the extracted text to the original ddf file.

writeIntermediateXsltCodeToFile - whether to safe the xslt code in a readable form. In any case, all location info is relative to the most concrete Write-out. (If false: in .ddf file. If true: in the xslt form and not the d2d form)

dateNow - for the creation comment in the generated files (=side effect for debugging)

fileBasis - directory for the generated files (=side effect for debugging)

lineWidth - for printing the intermediate files

Returns:

null in case of error

getTransformation_jre

public static Templates getTransformation_jre(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg,
 int tracelevel,
 Trace xsltTrace,
 ModuleRegistry moduleRegistry,
 Text2Udom.ErrorStrategy errorStrategy,
 ResolvedModule mod,
 String key,
 ResultContext resultContext,
 String topElementName,
 TransformationCache transformationsCache,
 Transformation.Modifiers txsl_modifiers,
 FunctionLibrary<?> functionLibrary,
 LocationMap<XMLDocumentIdentifier,XMLDocumentIdentifier> stringpos2filepos,
 boolean writeIntermediateXsltCodeToFile,
 @Opt
 @Opt String dateNow,
 @Opt
 @Opt String fileBasis,
 int lineWidth)

transformerException2errorMessage

public static boolean transformerException2errorMessage(Throwable ex,
 MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg,
 @Opt
 @Opt LocationMap<XMLDocumentIdentifier,XMLDocumentIdentifier> stringpos2filepos)

ATTENTION pure heuristics WHERE to find the error diagnosis !?!?!

Returns:

true iff an error message could be created.

getRootSourceLocator

@Opt
public static @Opt Location<XMLDocumentIdentifier> getRootSourceLocator(Throwable exception)

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

x_location

static Location<XMLDocumentIdentifier> x_location(@Opt
 @Opt String pub,
 String sys,
 int lin,
 int col)

Make a location with the given coordinates.

get_xslt_xml

@Opt
public static @Opt Tasks.XsltExtractionResult get_xslt_xml(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg,
 int tracelevel,
 Trace xsltTrace,
 ModuleRegistry moduleRegistry,
 Text2Udom.ErrorStrategy errorStrategy,
 ResolvedModule mod,
 String key,
 ResultContext resultContext,
 String topElementName,
 LocationMap<XMLDocumentIdentifier,XMLDocumentIdentifier> stringpos2filepos,
 boolean writeIntermediateXsltCodeToFile,
 @Opt
 @Opt String dateNow,
 @Opt
 @Opt String fileBasis,
 int lineWidth)

Because it is very unlikely that the same xslt source text must be processed by both Txsl and Jre-xslt, no cache is maintained for the intermediate Udom result, which in that rare case must be calculated twice.

ddf2xslt

public static void ddf2xslt(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg,
 int verbosity,
 ModuleRegistry moduleReg,
 @Opt
 @Opt Iterable<String> additionalSources,
 String modulename,
 String targetModule,
 @Opt
 @Opt String targetTopTag,
 String outputname,
 Text2Udom.ErrorStrategy errorStrategy,
 String genString,
 int lineWidth)

Service point: Extracts all xslt rules for the given module and target into a d2d definition and exports this to two xslt source files, in d2d and in xml encoding. Calls (MessageReceiver,ModuleRegistry,String,String, String,String,Text2Udom.ErrorStrategy errorStrategy,String,int,boolean) with "writeAdditionallyToXmlFile" set to true.

ddf2xslt

public static void ddf2xslt(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg,
 int verbosity,
 ModuleRegistry moduleReg,
 @Opt
 @Opt Iterable<String> additionalSources,
 String modulename,
 String targetModule,
 @Opt
 @Opt String targetTopTag,
 String outputname,
 Text2Udom.ErrorStrategy errorStrategy,
 String genString,
 int lineWidth,
 boolean writeAdditionallyToXmlFile)

Service point: Extracts all xslt rules for the given module and target into a d2d definition and exports this to a d2d source file. Then the d2d source is immediately parsed into an xml/xslt file. For this second step, the document type defintions of xslt and of the target language are required. The "outfile" parameter gives the directory where to store these results; the name of the files are derived from the module name and the target format as defined in Constants.filename_template_xslt_d2d and Constants.filename_template_xslt_xml, like
"[module.module]_to_[xhtml_1_0].xslt.d2d"
or
"[module.module]_to_[xhtml_1_0].xslt"

The d2d source will start with the indication of the target element and all namespaces involved:

      #d2d 2.0 xslt text producing [MODULE:ELEMENT]
         from  [PREF] = [NS_URI]
         from  [PREF] = [NS_URI]
 

Collects into the header all namespaces which appear in the tags of the source module (or module*S*, incl d2d-meta, etc).
The Text2Udom xslt parsing mode delivers these in a dedicated map.
This is necessary because the namespace-prefices appearing in xpath-constants only cannot be declared "in-place", since they exist only as XML attribute values. In template match="a:b" the prefix "a:" must be declared somewhere!

An immutable map can be read with Text2Udom.getXsltInputNamespaces().

Parameters:

targetTopTag - is only needed to find the reachable elements, for the xslt parsing. It may be ==null, indicating pure text.

writeAdditionallyToXmlFile - whether not only the d2d file but also the parsed xslt file in the xml format shall be written.

ddf2doc3

public static String ddf2doc3(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg,
 int tracelevel,
 ModuleRegistry moduleReg,
 String modulename,
 String language,
 boolean isStatic,
 String outputname,
 String gencomment,
 @Opt
 @Opt NamespaceName2String ext_stylesheetParams,
 @Opt
 @Opt Iterable<String> additionalSources,
 int lineWidth)

Service point: Generate the HTML documentation for a given module, ie. collect explicit doc texts in the selected language, and create Wirth-style graphics for the content models. In the instantiated version, only what is reachable from public definitions is shown.

Parameters:

additionalSources - source files which add further documentation text to definitions contained in a loaded module.

outputname - the path of the directory in which to create the generated documentation directory.

Returns:

the name of the generated documentation directory.

text2tdom

@Opt
public static <T extends TypedDocument,
D extends TypedDTD>
T text2tdom(@Opt
 @Opt File infile,
 ModuleRegistry modreg,
 Class<T> documentClass,
 D dtdInstance,
 MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msgr,
 Text2Udom.ErrorStrategy errorStrategy,
 int debug)

Service point: Convert a d2d input file into a tdom model. Ubiquituously callable for constructing a tdom model from a d2d input.
cf xantlrtdom/TdomReader.java Currently only USED in bandm.eu/bpm/book2/base/Main.java and in applics/src/eu/bandm/tools/jul/compiler/Model2Swing.java
Additionally Meta2Pi is inserted, to store d2d error messages transparently in a tdom model.

Returns:

null in case of load error

string2tdom

public static <T extends TypedDocument,
D extends TypedDTD>
T string2tdom(String sourcetext,
 ModuleRegistry modreg,
 Class<T> documentClass,
 D dtdInstance,
 MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msgr,
 Text2Udom.ErrorStrategy errorStrategy,
 int debug)

Convert a d2d source text into a tdom model.

text2xml

public static void text2xml(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> e_msg,
 int debuglevel,
 ModuleRegistry e_moduleReg,
 Text2Udom.ErrorStrategy errorStrategy,
 File e_sourcefile,
 Charset encoding,
 @Opt
 @Opt String generationComment,
 @Opt
 @Opt ContentHandler contentHandler,
 @Opt
 @Opt File xmlfile)

Service point: Convert directly a d2d encoded input text file into xml, either to a file or to a programmed consumer or to both.

1. parse text and create an untyped xml model Udom.
2. write out to an xml file and/or a SAX ContentHandler, if requested. (If neither is present, than acts as a type checker for text source and all referred definitions.)

Parameters:

debuglevel - if less than one all loggings are suppressed

text2xml

public static void text2xml(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> e_msg,
 int debuglevel,
 ModuleRegistry e_moduleReg,
 Text2Udom.ErrorStrategy errorStrategy,
 Reader e_source,
 @Opt
 @Opt String sourceIndication,
 @Opt
 @Opt String generationComment,
 @Opt
 @Opt ContentHandler contentHandler,
 @Opt
 @Opt File xmlfile)

Service point: Convert directly a d2d encoded text from a Reader into xml, either to a file or to a programmed consumer or to both.

1. parse text and create an untyped xml model Udom.
2. write out to an xml file and/or a SAX ContentHandler, if requested. (If neither is present, than acts as a type checker for text source and all referred definitions.)

Parameters:

debuglevel - if less than one all loggings are suppressed