org.decisiondeck.jmcda.xws.transformer
Class InputTransformer

java.lang.Object
  org.decisiondeck.jmcda.xws.transformer.InputTransformer

public class InputTransformer
extends Object

Constructor Summary

InputTransformer()

Method Summary

void	add(FunctionWithInputCheck<?,?> function) Adds the given transformer to the set of transformers this object uses.
static FunctionWithInputCheck<XMCDADoc,XmlObject>	functionDocToTag(String tagName)
static FunctionWithInputCheck<XMCDADoc,List<XmlObject>>	functionDocToTags(String tagName, boolean optional)
static FunctionWithInputCheck<File,InputSupplier<? extends InputStream>>	functionFileToSource()
static FunctionWithInputCheck<String,File>	functionNameToFile(File inputDirectory, boolean optional) Returns a function which, given a file name as a String, returns a File representing the given file, assuming the file is to be found in the given input directory.
static FunctionWithInputCheck<InputSupplier<? extends InputStream>,XMCDADoc>	functionSourceToDoc()
<B,C,D> D	get(Type targetType, Class<? extends FunctionWithInputCheck<Object,Object>> intermediateTransform, String name, File inputDirectory, boolean optional)
FunctionWithInputCheck<XMCDADoc,? extends XmlObject>	getDocToTag(String tagName)
FunctionWithInputCheck<XMCDADoc,List<XmlObject>>	getDocToTags(String tagName, boolean optional)
FunctionWithInputCheck<File,InputSupplier<? extends InputStream>>	getFileToSource()
FunctionWithInputCheck<String,XMCDADoc>	getNameToDoc(File inputDirectory, boolean optional) Returns a function which, given a file name as a String, returns an XMCDADoc containing the contents of the file, assuming the file is to be found in the given input directory.
FunctionWithInputCheck<String,File>	getNameToFile(File inputDirectory, boolean optional) Retrieves the alternative transformer from name to file set in this object, or the default one if none is set.
FunctionWithInputCheck<String,InputSupplier<? extends InputStream>>	getNameToSource(File inputDirectory, boolean optional) Retrieves the alternative transformer from name to source set in this object, or the default one if none is set.
FunctionWithInputCheck<String,? extends XmlObject>	getNameToTag(File inputDirectory, String tagName, boolean optional) Returns a function which, given a file name as a String, returns an XmlObject containing the fragment of the file corresponding to the given tagname, assuming the file is to be found in the given input directory.
FunctionWithInputCheck<String,List<XmlObject>>	getNameToTags(File inputDirectory, String tagName, boolean optional) Returns a function which, given a file name as a String, returns alist of XmlObjects containing the fragments of the file corresponding to the given tagname, assuming the file is to be found in the given input directory.
FunctionWithInputCheck<InputSupplier<? extends InputStream>,XMCDADoc>	getSourceToDoc()
<B,C,D> FunctionWithInputCheck<String,? extends D>	getTransformer(Type targetType, Class<? extends FunctionWithInputCheck<B,C>> intermediateTransform, File inputDirectory, boolean optional) Returns a transformer that chains transformation in order to pass from a String (supposedly containing a file name) to the given target type, and going through the given intermediate transformer if it is not null.
<V> FunctionWithInputCheck<String,V>	getTransformer(Type targetType, File inputDirectory, boolean optional) Retrieves a function that transforms from a String supposedly containing a file name to the given toType using a default strategy, assuming such a default transform is specified.
<F,V> FunctionWithInputCheck<F,? extends V>	getTransformerFrom(Class<? extends F> fromType, Type toType, File inputDirectory, boolean optional, boolean requireExactReturnType) Retrieves a function that transforms from the given fromType to the given toType using a default strategy, assuming such a default transform is specified.
void	setDocToTag(FunctionWithInputCheck<XMCDADoc,? extends XmlObject> docToTag)
void	setDocToTags(FunctionWithInputCheck<XMCDADoc,List<XmlObject>> docToTags)
void	setFileToSource(FunctionWithInputCheck<File,InputSupplier<? extends InputStream>> fileToSource)
void	setNameToFile(FunctionWithInputCheck<String,File> nameToFile)
void	setNameToSource(FunctionWithInputCheck<String,InputSupplier<? extends InputStream>> nameToSource)
void	setSourceToDoc(FunctionWithInputCheck<InputSupplier<? extends InputStream>,XMCDADoc> sourceToDoc)

Methods inherited from class java.lang.Object

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

Constructor Detail

InputTransformer

public InputTransformer()

Method Detail

add

public void add(FunctionWithInputCheck<?,?> function)

Adds the given transformer to the set of transformers this object uses. The given function must have a return type that is not already associated with a transformer.

Parameters:

function - not null.

functionNameToFile

public static FunctionWithInputCheck<String,File> functionNameToFile(File inputDirectory,
                                                                     boolean optional)

Returns a function which, given a file name as a String, returns a File representing the given file, assuming the file is to be found in the given input directory. For example, if the given input directory refers to a directory "dir", the returned function, when given the string "name", with return a handle to a file named "name" in the directory "dir". The returned function checks that the file exists before returning, if it does not, the returned function returns null or throws an InvalidInputException depending on whether the return value is optional.

Parameters:

inputDirectory - not null.

optional - if true, the function will return null when the referenced file does not exist, and does not throw InvalidInputException; if false, the function never returns null but throws an exception if the file to be returned does not exist.

Returns:

not null.

getNameToSource

public FunctionWithInputCheck<String,InputSupplier<? extends InputStream>> getNameToSource(File inputDirectory,
                                                                                           boolean optional)
                                                                                    throws InvalidInvocationException

Retrieves the alternative transformer from name to source set in this object, or the default one if none is set.

The default is to return a function which, given a file name as a String, returns a source referencing the given file, assuming the file is to be found in the given input directory. For example, if the given input directory refers to a directory "dir", the returned function, when given the string "name", with return a stream supplier reading from a file named "name" in the directory "dir". The returned function checks that the file exists before returning, if it does not, the returned function returns null or throws an InvalidInputException depending on whether the return value is optional.

if optional is true, the function will return null when the referenced file does not exist, and does not throw InvalidInputException; if false, the function never returns null but throws an exception if the file to be returned does not exist.

Parameters:

inputDirectory - non null if the default transformer is to be used.

optional - true if the transformer is allowed to return null, used only for the default transformer.

Returns:

not null.

Throws:

InvalidInvocationException - if the default name to file transformer is to be used, thus no alternative transformer is set, and the given input directory is null.

functionFileToSource

public static FunctionWithInputCheck<File,InputSupplier<? extends InputStream>> functionFileToSource()

getNameToDoc

public FunctionWithInputCheck<String,XMCDADoc> getNameToDoc(File inputDirectory,
                                                            boolean optional)
                                                     throws InvalidInvocationException

Returns a function which, given a file name as a String, returns an XMCDADoc containing the contents of the file, assuming the file is to be found in the given input directory. For example, if the given input directory refers to a directory "dir", the returned function, when given the string "name", with return a document containing the contents found in the file named "name" in the directory "dir". The returned function checks that the file exists before returning, if it does not, the returned function returns null or throws an InvalidInputException depending on whether the return value is optional.

Assuming that the file exists, the function retrieves the XMCDA document and ensures that it validates. The function throws an IOException if an exception happens while opening or closing the given reader, or while parsing the source, and throws an XmlException if an exception related to the contents of the source happens while parsing the source, including if the source document does not validate. Both are wrapped into an InvalidInputException.

If the document contained in the given source appears, according to its namespace, to be an XMCDA document not matching the expected version XMCDAReadUtils.DEFAULT_XMCDA_VERSION, this method attemps to proceed as if the source version matched the expected one.

Parameters:

inputDirectory - not null.

optional - if true, the function will return null when the referenced file does not exist; if false, the function never returns null but throws an exception if the file to be returned does not exist.

Returns:

not null.

Throws:

InvalidInvocationException - if the default name to file transformer is to be used, thus no alternative transformer is set, and the given input directory is null.

functionSourceToDoc

public static FunctionWithInputCheck<InputSupplier<? extends InputStream>,XMCDADoc> functionSourceToDoc()

getNameToTag

public FunctionWithInputCheck<String,? extends XmlObject> getNameToTag(File inputDirectory,
                                                                       String tagName,
                                                                       boolean optional)
                                                                throws InvalidInvocationException

Returns a function which, given a file name as a String, returns an XmlObject containing the fragment of the file corresponding to the given tagname, assuming the file is to be found in the given input directory. For example, if the given input directory refers to a directory "dir", and tagname is "alternatives", the returned function, when given the string "name", with return a xml fragment representing the tag "alternatives" and its content, found in the file named "name" in the directory "dir". If the file does not exist, the returned function returns null or throws an InvalidInputException depending on whether the return value is optional.

Assuming that the file exists, the function retrieves the XMCDA document and ensures that it validates. The function throws an IOException if an exception happens while opening or closing the given reader, or while parsing the source, and throws an XmlException if an exception related to the contents of the source happens while parsing the source, including if the source document does not validate. Both are wrapped into an InvalidInputException. Then, the function reads the content of the document. If the given tag is not found or more than one is found, an InvalidInputException is thrown. Otherwize, an xml object representing the tag contents is returned.

If the document contained in the given source appears, according to its namespace, to be an XMCDA document not matching the expected version XMCDAReadUtils.DEFAULT_XMCDA_VERSION, this method attemps to proceed as if the source version matched the expected one.

Parameters:

inputDirectory - not null.

tagName - not null.

optional - if true, the function will return null when the referenced file does not exist; if false, the function never returns null but throws an exception if the file to be returned does not exist.

Returns:

not null.

Throws:

InvalidInvocationException - if the default name to file transformer is to be used, thus no alternative transformer is set, and the given input directory is null.

getDocToTag

public FunctionWithInputCheck<XMCDADoc,? extends XmlObject> getDocToTag(String tagName)

getNameToTags

public FunctionWithInputCheck<String,List<XmlObject>> getNameToTags(File inputDirectory,
                                                                    String tagName,
                                                                    boolean optional)
                                                             throws InvalidInvocationException

Returns a function which, given a file name as a String, returns alist of XmlObjects containing the fragments of the file corresponding to the given tagname, assuming the file is to be found in the given input directory. For example, if the given input directory refers to a directory "dir", and tagname is "alternatives", the returned function, when given the string "name", with return xml fragments representing the tags "alternatives" and their content, found in the file named "name" in the directory "dir". Assuming the given file would contain two tags named "alternatives", the returned list would contain two xml objects, each one corresponding to one of the tags, listed in document order.

If the file does not exist, the returned function returns null or throws an InvalidInputException depending on whether the return value is optional.

Assuming that the file exists, the function retrieves the XMCDA document and ensures that it validates. The function throws an IOException if an exception happens while opening or closing the given reader, or while parsing the source, and throws an XmlException if an exception related to the contents of the source happens while parsing the source, including if the source document does not validate. Both are wrapped into an InvalidInputException. Then, the function reads the content of the document. If the given tag is not found, an InvalidInputException is thrown. Otherwize, xml objects representing the tags contents are returned, one object per tag matching the given tag name.

If the document contained in the given source appears, according to its namespace, to be an XMCDA document not matching the expected version XMCDAReadUtils.DEFAULT_XMCDA_VERSION, this method attemps to proceed as if the source version matched the expected one.

Parameters:

inputDirectory - not null.

tagName - not null.

optional - if true, the function will return null when the referenced file does not exist; if false, the function never returns null but throws an exception if the file to be returned does not exist.

Returns:

not null.

Throws:

InvalidInvocationException - if the default name to file transformer is to be used, thus no alternative transformer is set, and the given input directory is null.

functionDocToTags

public static FunctionWithInputCheck<XMCDADoc,List<XmlObject>> functionDocToTags(String tagName,
                                                                                 boolean optional)

getTransformer

public <V> FunctionWithInputCheck<String,V> getTransformer(Type targetType,
                                                           File inputDirectory,
                                                           boolean optional)
                                                throws InvalidInvocationException

Retrieves a function that transforms from a String supposedly containing a file name to the given toType using a default strategy, assuming such a default transform is specified. For example, if the to type is File, the returned function, when given a String, returns a File referencing the file named according to the String given to the function, and found in the input directory given as parameter to this method, according to the description of functionNameToFile(File, boolean).

If toType is String, the identity function is returned.

The toType must be chosen in the following list: String, File, InputSupplier (of InputStream extended streams), XMCDADoc, XmlObject or list of xml objects.

Type Parameters:

V - the codomain of the function: the type of value it returns, which is also the to type.

Parameters:

targetType - not null.

inputDirectory - may be null.

optional - true to allow the function to return a null value if the file does not exist.

Returns:

not null.

Throws:

InvalidInvocationException - if the default name to file transformer is to be used, thus no alternative transformer is set and the toType is not String, and the given input directory is null.

getTransformerFrom

public <F,V> FunctionWithInputCheck<F,? extends V> getTransformerFrom(Class<? extends F> fromType,
                                                                      Type toType,
                                                                      File inputDirectory,
                                                                      boolean optional,
                                                                      boolean requireExactReturnType)
                                                         throws InvalidInvocationException

Retrieves a function that transforms from the given fromType to the given toType using a default strategy, assuming such a default transform is specified. For example, if fromType is String and the to type is File, the returned function, when given a String, returns a File referencing the file named according to the String given to the function, and found in the input directory given as parameter to this method, according to the description of functionNameToFile(File, boolean).

If fromType equals toType, the identity function is returned.

The fromType and toType must be chosen in the following list: String, File, InputSupplier (of InputStream extended streams), XMCDADoc, XmlObject or subclasses, or parameterized list (or superclass) of xml objects or subclasses. The to type must come later down the list compared to the from type.

Note that the optional parameter is only used to transform from a String to a File. If e.g. the from type is File and the to type is InputSupplier, the returned function, when given a null argument, returns null irrespective of the optional parameter value, whereas it should throw an exception when optional is false. This works for as long as caution is exercised not to give the returned function a null argument when optional is false.

Type Parameters:

F - the domain of the function: the type of value it expects, which is also the from type.

V - the codomain of the function: the type of value it returns, which is also the to type.

Parameters:

fromType - not null.

toType - not null.

inputDirectory - may be null.

optional - true to allow the function to return a null value if the file does not exist.

requireExactReturnType - if true, the returned function has a codomain of exactly V instead of something extending V, the drawback being that the toType must also be exactly V, not some subtype of an allowed entry. For example, if the argument is false, a Collection is allowed to play the role of a List as a valid toType. Note that the from type is not checked exactly, irrespective of the value of this parameter.

Returns:

not null.

Throws:

InvalidInvocationException - if the default name to file transformer is to be used, thus no alternative transformer is set and the fromType is String and the toType is not String, and the given input directory is null.

getTransformer

public <B,C,D> FunctionWithInputCheck<String,? extends D> getTransformer(Type targetType,
                                                                         Class<? extends FunctionWithInputCheck<B,C>> intermediateTransform,
                                                                         File inputDirectory,
                                                                         boolean optional)
                                                          throws InvalidInvocationException

Returns a transformer that chains transformation in order to pass from a String (supposedly containing a file name) to the given target type, and going through the given intermediate transformer if it is not null. The returned transformer implements a default strategy to transform the String to type B, then the intermediate transformer is instantiated and used to transform the object of type B to an object of type C, then again the default strategy is used to get a final object of type D. If some of these types are equal, for example C and D, no transformation occurs for that step.

Type Parameters:

B - the input type of the intermediate transformer, if given. If it is not String, a string will be transformed to a type B by using the default transform strategy.

C - the output type of the intermediate transformer, if given.

D - the type that the returned function outputs.

Parameters:

targetType - the type that the returned function outputs.

intermediateTransform - may be null.

inputDirectory - may be null if unused.

optional - if true, the returned function will return null when the file does not exist instead of throwing an exception.

Returns:

not null.

Throws:

InvalidInvocationException - if the default name to file transformer is to be used and the given input directory is null.

get

public <B,C,D> D get(Type targetType,
                     Class<? extends FunctionWithInputCheck<Object,Object>> intermediateTransform,
                     String name,
                     File inputDirectory,
                     boolean optional)
      throws InvalidInputException,
             InvalidInvocationException

Throws:

InvalidInputException

InvalidInvocationException

functionDocToTag

public static FunctionWithInputCheck<XMCDADoc,XmlObject> functionDocToTag(String tagName)

getDocToTags

public FunctionWithInputCheck<XMCDADoc,List<XmlObject>> getDocToTags(String tagName,
                                                                     boolean optional)

setDocToTags

public void setDocToTags(FunctionWithInputCheck<XMCDADoc,List<XmlObject>> docToTags)

getFileToSource

public FunctionWithInputCheck<File,InputSupplier<? extends InputStream>> getFileToSource()

setFileToSource

public void setFileToSource(FunctionWithInputCheck<File,InputSupplier<? extends InputStream>> fileToSource)

getNameToFile

public FunctionWithInputCheck<String,File> getNameToFile(File inputDirectory,
                                                         boolean optional)
                                                  throws InvalidInvocationException

Retrieves the alternative transformer from name to file set in this object, or the default one if none is set.

Parameters:

inputDirectory - non null if the default transformer is to be used.

optional - true if the transformer is allowed to return null, used only for the default transformer.

Returns:

not null.

Throws:

InvalidInvocationException - if the default transformer is to be used, thus no alternative transformer is set, and the given input directory is null.

setNameToFile

public void setNameToFile(FunctionWithInputCheck<String,File> nameToFile)

getSourceToDoc

public FunctionWithInputCheck<InputSupplier<? extends InputStream>,XMCDADoc> getSourceToDoc()

setSourceToDoc

public void setSourceToDoc(FunctionWithInputCheck<InputSupplier<? extends InputStream>,XMCDADoc> sourceToDoc)

setDocToTag

public void setDocToTag(FunctionWithInputCheck<XMCDADoc,? extends XmlObject> docToTag)

setNameToSource

public void setNameToSource(FunctionWithInputCheck<String,InputSupplier<? extends InputStream>> nameToSource)