com.sodius.mdw.core.eval
Interface GeneratedCode


public interface GeneratedCode

Describes the evaluation output of a text template. The output of a text template has the following properties :

A generated code is created when a text template is evaluated, and its contents can be persistent using the write() method.

This interface is not intended to be implemented by clients.

See Also:
EvaluationContext.generate(String, List)

Method Summary
 void addEndProtectedSection(String endTag)
          Ends a protected section.
 void addProtectedSection(String startTag, String endTag)
          Adds a protected section.
 void addProtectedSections(Collection<ProtectedSection> sections)
          Adds each protected section of the collection.
 void addStartProtectedSection(String startTag)
          Starts a protected section.
 void discard()
          Notifies this generated code it must be discarded.
 String getContents()
          Returns the contents generated by the text template.
 InputSource getContentSource()
          Returns the contents generated by the text template.
 String getEncoding()
          Returns the encoding to use when writing the generated contents.
 File getFile()
          Returns the file path specified in the text template.
 List<ProtectedSection> getProtectedSections()
          Returns the list of protected sections, which define regions in a file that can contain end-user manual code and that the generator must never overwrite.
 boolean isDiscarded()
          Returns true if this generated code is discarded and must not be written.
 void setContents(InputSourceProvider contentsProvider)
          Sets the generated contents.
 void setContents(String contents)
          Sets the generated contents.
 void setEncoding(String encoding)
          Sets the encoding to use when writing the generated contents.
 void setFile(File file)
          Sets the file, which may be relative, where the generated contents should be written out.
 void write()
          Writes this generated contents into the underlying file on disk.
 

Method Detail

getFile

File getFile()
Returns the file path specified in the text template. This file corresponds to the path generated by the text template. At this time the path is not resolved against the current evaluation directory, so it may be a relative path. This file can be null if no the text template has no file property.

Returns:
the file path generated by the text template (can be null).

setFile

void setFile(File file)
Sets the file, which may be relative, where the generated contents should be written out.

Parameters:
file - the file where to write the generated contents.

getEncoding

String getEncoding()
Returns the encoding to use when writing the generated contents. If this encoding is null, which is the general case, the platform default encoding is used. The encoding can be used for example when generating XML files, since it must match the declaration of the XML header (UTF-8 for example).

Returns:
the encoding to use, null if no encoding specified.

setEncoding

void setEncoding(String encoding)
Sets the encoding to use when writing the generated contents. If this encoding is null, which is the general case, the platform default encoding is used. The encoding can be used for example when generating XML files, since it must match the declaration of the XML header (UTF-8 for example).

Parameters:
encoding - the encoding to use, null to use the platform default encoding.

getContents

String getContents()
Returns the contents generated by the text template. This contents is not merged with the underlying existing file at this time.

Returns:
the generated contents, null if not specified.

setContents

void setContents(String contents)
Sets the generated contents.

Parameters:
contents - the contents generated by the text template.

getContentSource

InputSource getContentSource()
                             throws IOException
Returns the contents generated by the text template. This contents is not merged with the underlying existing file at this time.

Returns:
the generated contents, null if not specified.
Throws:
IOException
Since:
3.2.0

setContents

void setContents(InputSourceProvider contentsProvider)
Sets the generated contents.

Parameters:
contentsProvider - the contents generated by the text template.
Since:
3.2.0

addProtectedSection

void addProtectedSection(String startTag,
                         String endTag)
Adds a protected section. Start and end tags can be any arbitrary (language specific) strings, including multiline strings (with '\n' characters). A start delimiter must be unique in the scope of the generated file.

Parameters:
startTag - the start delimiter.
endTag - the end delimiter.

addStartProtectedSection

void addStartProtectedSection(String startTag)
Starts a protected section. The start can be any arbitrary (language specific) string, including multiline string (with '\n' characters). A start delimiter must be unique in the scope of the generated file.

Parameters:
startTag - the start delimiter.
See Also:
addEndProtectedSection(String)

addEndProtectedSection

void addEndProtectedSection(String endTag)
Ends a protected section. The end tag can be any arbitrary (language specific) string, including multiline string (with '\n' characters)

Parameters:
endTag - the start delimiter.
See Also:
addStartProtectedSection(String)

addProtectedSections

void addProtectedSections(Collection<ProtectedSection> sections)
Adds each protected section of the collection.

Parameters:
sections - a collection of ProtectedSection elements.

getProtectedSections

List<ProtectedSection> getProtectedSections()
Returns the list of protected sections, which define regions in a file that can contain end-user manual code and that the generator must never overwrite.

Returns:
an unmodifiable list of ProtectedSection elements, ordered the way they were added.

write

void write()
           throws EvaluationException
Writes this generated contents into the underlying file on disk.

Writing a generated code consists of the following steps :

Note : template and script designers should generally not have to consider this method. The EvaluationContext.generate(String, List) method evaluates the template and write it automaticaly on disk. This method is only to be used if the template has been evaluated with the EvaluationContext.createGeneratedCode(String, List) method.

Throws:
EvaluationException - if the generated contents could not be written on disk. Reasons include :
  • The file is not specified or is invalid.
  • The encoding is not supported
  • An exception occured during the file writing.
See Also:
EvaluationContext.generate(String, List), EvaluationConfiguration.getEvaluationDirectory(), EvaluationConfiguration.isFileOverwriteForced()

isDiscarded

boolean isDiscarded()
Returns true if this generated code is discarded and must not be written. A generated code is discarded when the related text template guard failed. Any attempt to write a discarded generated code would fail.

Returns:
true if the generated code is discarded, false otherwise.

discard

void discard()
Notifies this generated code it must be discarded. A generated code is discarded when the related text template guard failed.