xbn.template
Class TemplateFiller

java.lang.Object
  |
  +--xbn.XBNObject
        |
        +--xbn.template.TemplateFiller

public class TemplateFiller

extends XBNObject

Take a Template, fill each gap with something, and output the resulting text.

Source code: TemplateFiller.java. Example code XmplTemplateFiller.java

Overview for using TemplateFiller

1. Create a Template.
2. Set it into this TemplateFiller.
3. Fill in all of the Template's gaps.
4. Get the resulting output, via getResult, or if you want output printed to an alternative location, set any specific OWriter with setOWriter. This must be done before setting the template. When an alternative OWriter has been set, there is no need to getResult.

Examples: One, two and demonstration of how output is built on the fly.

TOP Example One

Take this text...

Hello there, ~G~name~EG~. Through significant research, ~G~name~EG~, it has been discovered that you are exactly ~G~age~EG~ years old.

...and this code...

Template t = new Template(FLRFile("[...file path to text file...]"));
TemplateFiller tf = new TemplateFiller();
tf.setTemplate(t);
tf.fill("name", "Jeffy");
tf.fill("age", 30);
sopl(tf.getResult());

...and here's the output:

Hello there, Jeffy. Through significant research, Jeffy, it has been discovered that you are exactly 30 years old.

TOP Example Two

Take this text...

~G~name~EG~~G~name~EG~

There's an example of a gap at the very beginning of the file, and of two gaps directly next to each other.

Following is an example of the same, but at the <I>end</I> of the file.

~G~age~EG~~G~age~EG~

...and the same code as in example one, and here's the output:

JeffyJeffy

There's an example of a gap at the very beginning of the file, and of two gaps directly next to each other.

Following is an example of the same, but at the <I>end</I> of the file.

3030

TOP Example Three: Step By Step, How Resulting Text is built.

Given the template in example one...

Hello there, ~G~name~EG~. Through significant research, ~G~name~EG~, it has been discovered that you are exactly ~G~age~EG~ years old.

...here are the internal TemplateData objects:

AOSLookup, part one: The unique array of UniqueStrings

getString	getUnqArrIdx	getInstanceCount
name	0	2
age	1	1

AOSLookup, part two: The unique array of UniqueStrings

getString	getUnqArrIdx	getInstanceCount
name	0	2
name	0	2
age	1	1

AOSLookup, part three: AOSLHashtable

Key (unique string)	Value (UniqueString)
name	[name, 0, 2]
age	[age, 1, 1]

Lastly, the array of surrounding text:

["Hello there, ", ". Through significant research, ", ", it has been discovered that you are exactly ", "years old."]

How the resulting output is built

The output is built on the fly. Before any gaps are even filled, we already know how the result will start...with the first element of surrounding text:

Hello there,

We've reached the first gap. The first absolute gap. Array index zero. What is the name of this gap? We need the unique name of this gap, knowing that the absolute array index is zero...

String sGapName = getAOSLookup().getUSAPAbsolute().getUniqueString(i).getString();

The first absolute gap name is "name". Until it is filled, the result text will remain in this state. If the "age" gap is filled before the "name" gap is filled, this resulting output text remains unchanged.

Now, say the "name" gap was filled (with the value "Jeffy"). The resulting output can be further constructed. First, append the fill text for it:

Hello there, Jeffy

Now get element two (array index zero) of the surrounding text, and add it:

Hello there, Jeffy. Through significant research,

Now we've reached the second absolute gap (array index one). What is the name of this gap, knowing that the absolute array index? By calling the same code as above (with "1" instead of "0"), we find that the second absolute gap is a duplicate of the first: "name". We know that this gap has already been filled, so we can proceed. Take the same fill text and append it to the output:

Hello there, Jeffy. Through significant research, Jeffy

Add the next item of the surrounding text (the third element, array index two):

Hello there, Jeffy. Through significant research, Jeffy, it has been discovered that you are exactly

Now we've reached the third absolute gap (array index two). What is the name of this gap, knowing the absolute array index? The gap name is "age".

Gap "age" has not been filled yet, so the output remains as it is.

...Gap "age" has still not been filled...

...Okay, there we are. Gap "age" has been filled. Get the fill text for it, and append it onto the resulting output:

Hello there, Jeffy. Through significant research, Jeffy, it has been discovered that you are exactly 30

Add the next surrounding text to the output:

Hello there, Jeffy. Through significant research, Jeffy, it has been discovered that you are exactly 30 years old.

We've reached the end of the surrounding text array. By definition, there is exactly one more surrounding text element than there are absolute gaps. Therefore, outputting the last element of surrounding text is a way of detecting that the result output has been completely constructed.

Ta-da.

Fields inherited from class xbn.XBNObject

bFALSE_IN_PRODUCTION, bTRUE_IN_PRODUCTION, sCNSTR, sES, sLINE_SEP

Constructor Summary

TemplateFiller()
Create a TemplateFiller.

TemplateFiller(boolean b_allowSetOWInMidFill)
Create a TemplateFiller.

TemplateFiller(OWriter o_writer)
Create a TemplateFiller.

TemplateFiller(OWriter o_writer, boolean b_allowSetOWInMidFill)
Create a TemplateFiller.

Method Summary

boolean	areAllGapsFilled() Have all the currently-set Template's gaps been filled?
void	dbg(String s)
void	dbgnl(String s)
void	declareExtFillComplete() Declare that the external fill has been completed.
boolean	doAllowOWSetInMidFill() Is it legal to call setOWriter/setOWIntoSB in mid-fill?
void	fill(String s_gapName, boolean b_fillValue) Fill in the requested gap with a boolean value.
void	fill(String s_gapName, int i_fillValue) Fill in the requested gap with an int value.
void	fill(String s_gapName, String s_fillText) Fill in the requested gap with a string value.
void	fill(String s_gapName, TemplateOrderedGaps t_rdrdGaps, String[] as_fillText) Fill in a single gap in the currently-set Template with the resulting text from a TemplateOrderedGaps.
void	fill(String s_gapName, TOGOne tog_1, String s_fillText) Fill in a single gap in the currently-set Template with the resulting text from a TOGOne.
void	fill(String s_gapName, TOGThree tog_3, String s_fillText1, String s_fillText2, String s_fillText3) Fill in a single gap in the currently-set Template with the resulting text from a TOGThree.
void	fill(String s_gapName, TOGTwo tog_2, String s_fillText1, String s_fillText2) Fill in a single gap in the currently-set Template with the resulting text from a TOGTwo.
void	forceReset() Reset this TemplateFiller to its original state...as if you never set a Template or filled any gaps within it.
String	getAllFilledWith(Template t_emplate, String s_fillText) Provide a template and fill all of it's gaps with the same fill text.
int	getGapsFilledCount() How many gaps have been filled so far?
String[]	getGapsNotYetFilled() Get a String array containing all unique gap names that have yet to be filled.
int	getGapsNotYetFilledCount() How many gaps have not yet been filled?
String	getMidExtFillGapName() If we're currently in the middle of an external fill, what is the gap name that is being filled?
int	getNextAbsGapArrIdxNYF() Get the array index of the next absolute gap not yet filled.
String	getNextAbsGapNameNYF() Get the name of the next absolute gap not yet filled.
Outputter	getOptrDbg()
OWriter	getOWForExtFill(String s_gapName) Get the OWriter for an external fill.
OWIntoSB	getOWIntoSB() Get the OWIntoSB for direct manipulation.
OWriter	getOWriter() Get the OWriter for direct manipulation.
String	getResult() Get the resulting text from the Template, and all its filled gaps.
Template	getTemplate() Get the Template for direct manipulation.
boolean	hasGapBeenFilled(String s_gapName) Has the gap with the provided name been filled?
boolean	isFilled(String s_gapName) Has the requested gap been filled?
boolean	isFillLegal() Is it legal to fill a gap?
boolean	isMidExtFill() Is this TemplateFiller currently in the middle of an external fill?
boolean	isOWriterOWIntoSB() Is the OWriter an OWIntoSB?
boolean	isTemplateSet() Is a template currently set into this TemplateFiller?
void	reGap(String s_gapName) Refill the gap with the gap itself.
void	reGap(String s_gapName, String s_gapStart, String s_gapEnd) Refill the gap with the gap itself.
void	setAllowOWSetInMidFill(boolean b_allowSetOWInMidFill) Declare if it legal to call setOWriter/setOWIntoSB in mid-fill.
void	setOptrDbg(Outputter optr_dbg)
void	setOWIntoSB() Eliminate the current OWriter, and replaces it with a new OWIntoSB object.
void	setOWriter(OWriter o_writer) Set an OWriter into this TemplateFiller.
void	setTemplate(Template t_emplate) Which Template do you want to fill?

Methods inherited from class xbn.XBNObject

getXMsgPrefix, sop, sopl, sopl, throwAX, throwAXIfBadStr, throwAXIfNull, throwAXSpoof

Methods inherited from class java.lang.Object

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

Constructor Detail

TemplateFiller

public TemplateFiller()

Create a TemplateFiller.

Equal to TemplateFiller(false)

TemplateFiller

public TemplateFiller(boolean b_allowSetOWInMidFill)

Create a TemplateFiller.

Note that setOWIntoSB is called by this constructor.

Parameters:

b_allowSetOWInMidFill - If true, then you may repeatedly set different OWriters into this TemplateFiller, even if you're currently in the middle of filling a Template's gaps (this might be useful for testing and verification purposes. Not sure how it would be useful for real...). If false, then attempting to set a new OWriter while in mid-fill will cause an AssertException to be thrown.

TemplateFiller

public TemplateFiller(OWriter o_writer,
                      boolean b_allowSetOWInMidFill)

Create a TemplateFiller.

Parameters:

o_writer - The OWriter that will be used to write output in this TemplateFiller. See setOWriter and getOWriter

b_allowSetOWInMidFill - If true, then you may repeatedly set different OWriters into this TemplateFiller, even if you're currently in the middle of filling a Template's gaps (this might be useful for testing and verification purposes. Not sure how it would be useful for real...). If false, then attempting to set a new OWriter while in mid-fill will cause an AssertException to be thrown.

TemplateFiller

public TemplateFiller(OWriter o_writer)

Create a TemplateFiller.

Equal to TemplateFiller(o_writer, false)

Method Detail

isFillLegal

public boolean isFillLegal()

Is it legal to fill a gap?

Returns:

true If isTemplateSet is true, and areAllGapsFilled is false.
false If isTemplateSet is false, or isTemplateSet is true but areAllGapsFilled is true as well.

areAllGapsFilled

public boolean areAllGapsFilled()

Have all the currently-set Template's gaps been filled?

Returns:

(([THE NUMBER OF GAPS FILLED SO FAR] - 1) >= getTemplate().getUSAPAbsolute().getLength())

Throws:

AssertException - If isTemplateSet is false.

setTemplate

public final void setTemplate(Template t_emplate)

Which Template do you want to fill?

Get with getTemplate. Analyze with isTemplateSet.

Parameters:

t_emplate - The Template to fill. May not be null.

Throws:

AssertException - If isTemplateSet equals true and areAllGapsFilled is false. This means that you've already set the template, and have not yet completely filled it, or have not gotten the result.

getTemplate

public final Template getTemplate()

Get the Template for direct manipulation.

Set with setTemplate. Analyze with isTemplateSet.

Returns:

t_emplate, exactly as provided to setTemplate.
null If no template is currently set.

isTemplateSet

public final boolean isTemplateSet()

Is a template currently set into this TemplateFiller?

Set with setTemplate. Get with getTemplate.

Returns:

true Yes. A template is currently set into this TemplateFiller
false No. No template is set.

getNextAbsGapArrIdxNYF

public final int getNextAbsGapArrIdxNYF()

Get the array index of the next absolute gap not yet filled. See getNextAbsGapNameNYF

This is important when doing external fills.

getNextAbsGapNameNYF

public final String getNextAbsGapNameNYF()

Get the name of the next absolute gap not yet filled. See getNextAbsGapArrIdxNYF.

This is important when doing external fills.

Returns:

getTemplate().getUSAPAbsolute().getUniqueString(getNextAbsGapArrIdxNYF())

Throws:

AssertException - if isTemplateSet equals false.

hasGapBeenFilled

public final boolean hasGapBeenFilled(String s_gapName)

Has the gap with the provided name been filled?

Parameters:

s_gapName - The name of the gap.

Returns:

true If this gap has been filled.
false If it has not yet been filled.

Throws:

AssertException - if isTemplateSet equals false.

getOWForExtFill

public final OWriter getOWForExtFill(String s_gapName)

Get the OWriter for an external fill. After you have completed filling this gap, you must declare this with declareExtFillComplete.

See getMidExtFillGapName, declareExtFillComplete and isMidExtFill.

An external fill is best for large, process intensive gaps. If you compile the text of this gap, and then--only after you have it all--fill the gap with it, then there will be a long pause while the gap text is being retrieved. Then, all of the sudden, all that text will just "snap" to the screen, as soon as the fill is executed. An external fill allows your text to be "streamed" to the user, on the fly.

The following conditions must be met before an external fill is legal:

• isTemplateSet must equal true.
• isMidExtFill must be false. You may not be in the middle of another external fill.
• hasGapBeenFilled(s_gapName) must equal false. You can't fill the same gap twice.
• getTemplate().getTemplateData().getAOSLookup().getAOSLHashtable().getUniqueString(s_gapName).isSingular() must be true. If there are more than one instance of this unique gap in the source text, an external fill won't work. See declareExtFillComplete.
• getNextAbsGapNameNYF().equals(s_gapName) must be true. If this condition is not met, you'll get a list of all the absolute gaps preceding this one, in the error message.

Since there are so many requirements for an external fill, it is safest to postpone all external fills until all other gaps have been filled. It is also recommended that you check all Templates at the start of your program, to ensure that the to-be-externally-filled gaps are found where you expect.

Parameters:

s_gapName - The name of the gap to fill externally.

isMidExtFill

public final boolean isMidExtFill()

Is this TemplateFiller currently in the middle of an external fill?

See getMidExtFillGapName, declareExtFillComplete and getOWForExtFill.

Returns:

true If getOWForExtFill has most recently been called, after declareExtFillComplete.
false If declareExtFillComplete has most recently been called, after getOWForExtFill.

getMidExtFillGapName

public final String getMidExtFillGapName()

If we're currently in the middle of an external fill, what is the gap name that is being filled?

See isMidExtFill, declareExtFillComplete and getOWForExtFill.

Returns:

s_gapName exactly as passed into getOWForExtFill.
null If isMidExtFill equals false.

declareExtFillComplete

public final void declareExtFillComplete()

Declare that the external fill has been completed.

See isMidExtFill, getMidExtFillGapName and getOWForExtFill.

This does exactly one thing...

fill(getMidExtFillGapName(), sES)

...which is why an external gap must be singular. If there are more than one instance of this gap in the source text, then an extenal fill could only populate one of those instances. The rest of the instances could only be populated by (in this case) empty string.

If you truly wanted to populate all instances with the same text, then you'd have to hold the result in memory, and output it in all the instances' locations. Since an external fill is generally for larger and more process intensive gaps, this is not a good idea.

Returns:

s_gapName exactly as passed into getOWForExtFill.

Throws:

AssertException - if isMidExtFill equals false.

fill

public final void fill(String s_gapName,
                       TOGOne tog_1,
                       String s_fillText)

Fill in a single gap in the currently-set Template with the resulting text from a TOGOne.

Parameters:

s_gapName - The name of the gap to fill in the currently-set Template. Passed directly to fill.

tog_1 - The TemplateOrderedGaps object, whose resulting text should fill in the gap name s_gapName, as existing in the currently-set Template. May not be null.

s_fillText1 - The fill text for the only unique gap existing in tog_1. May not be null.

fill

public final void fill(String s_gapName,
                       TOGTwo tog_2,
                       String s_fillText1,
                       String s_fillText2)

Fill in a single gap in the currently-set Template with the resulting text from a TOGTwo.

Parameters:

s_gapName - The name of the gap to fill in the currently-set Template. Passed directly to fill.

tog_2 - The TemplateOrderedGaps object, whose resulting text should fill in the gap name s_gapName, as existing in the currently-set Template. May not be null.

s_fillText1 - The fill text for the first of two unique gaps existing in tog_2. May not be null.

s_fillText2 - The fill text for the second of two unique gaps existing in tog_2. May not be null.

fill

public final void fill(String s_gapName,
                       TOGThree tog_3,
                       String s_fillText1,
                       String s_fillText2,
                       String s_fillText3)

Fill in a single gap in the currently-set Template with the resulting text from a TOGThree.

Parameters:

s_gapName - The name of the gap to fill in the currently-set Template. Passed directly to fill.

tog_3 - The TemplateOrderedGaps object, whose resulting text should fill in the gap name s_gapName, as existing in the currently-set Template. May not be null.

s_fillText1 - The fill text for the first of three unique gaps existing in tog_3. May not be null.

s_fillText2 - The fill text for the second of three unique gaps existing in tog_3. May not be null.

s_fillText3 - The fill text for the third of three unique gaps existing in tog_3. May not be null.

reGap

public final void reGap(String s_gapName)

Refill the gap with the gap itself.

Equal to reGap(s_gapName, getTemplate().getTagStart(), getTemplate().getTagEnd())

Note, if isTemplateSet equals false, an AssertException is thrown, not a NullPointerException.

reGap

public final void reGap(String s_gapName,
                        String s_gapStart,
                        String s_gapEnd)

Refill the gap with the gap itself.

This will make the gap appear as it originally existed in the template source text. Note that the gap is considered filled.

Equal to fill(s_gapName, s_gapStart + s_gapName + s_gapStart)

Throws:

AssertException - If isTemplateSet is equal to false.

fill

public final void fill(String s_gapName,
                       TemplateOrderedGaps t_rdrdGaps,
                       String[] as_fillText)

Fill in a single gap in the currently-set Template with the resulting text from a TemplateOrderedGaps.

Parameters:

s_gapName - The name of the gap to fill in the currently-set Template. Passed directly to fill.

t_rdrdGaps - The TemplateOrderedGaps object, whose resulting text should fill in the gap name s_gapName, as existing in the currently-set Template. May not be null.

as_fillText - The array of fill text to be applied to t_rdrdGaps. Must not be null, and must have the same length as t_rdrdGaps.getUSAPUnique().getLength().

fill

public final void fill(String s_gapName,
                       String s_fillText)

Fill in the requested gap with a string value.

Parameters:

s_gapName - The name of the gap to be fill. Must exist according to getTemplate().getAOSLHashtable().containsKey(s_gapName).

s_fillText - The text to fill the gap with. May not be null. This may be (or contain) another gap. For example:

"This is the text that ~G~name~EG~ wants to fill this gap with."

fill

public final void fill(String s_gapName,
                       int i_fillValue)

Fill in the requested gap with an int value.

Equal to fill(s_gapName, (new Integer(i_fillValue)).toString())

fill

public final void fill(String s_gapName,
                       boolean b_fillValue)

Fill in the requested gap with a boolean value.

Equal to fill(s_gapName, (new Boolean(b_fillValue)).toString())

isFilled

public final boolean isFilled(String s_gapName)

Has the requested gap been filled?

Parameters:

s_gapName - The requested gap. Must equal the name of an existing gap.

Returns:

Has the gap at array index

getTemplate().getAOSLHashtable().getUniqueString(s_gapName).getUnqArrIdx()

been filled? If yes, return true, otherwise false.

Throws:

AssertException - If isTemplateSet equals false.

getResult

public final String getResult()

Get the resulting text from the Template, and all its filled gaps. The template is unset by this function.

NOTE: This function may only be used when getOWriter is of type xbn.output.OWIntoSB

For specifics on how the output (as returned by this function) is built, see the example in the documentation overview. The resulting output is built on the fly, as the gaps are filled, and not by this function. Before getOWForExtFill existed, this function did build this output. External fills are one of the more powerful recent additions to this class.

Returns:

The entire template with all gaps replaced with text, and filled by this TemplateFiller.

Throws:

AssertException -

• If isTemplateSet returns false.
• If getGapsNotYetFilled is not null.
• If getOWriter happens to be of a type other than xbn.output.OWIntoSB

getAllFilledWith

public final String getAllFilledWith(Template t_emplate,
                                     String s_fillText)

Provide a template and fill all of it's gaps with the same fill text. This function will work even if you're currently in the middle of filling another Template's gaps.

Why use this function at all? One realistic usage is for database SQL that will be used in a PreparedStatement. See DBCSPrepared for information.

forceReset

public final void forceReset()

Reset this TemplateFiller to its original state...as if you never set a Template or filled any gaps within it.

This should really really really not ever be used, except perhaps during debugging and development phases.

Note that this function leaves the curent OWriter alone. The only exception to this rule is if isOWriterOWIntoSB is true. In that case getOWIntoSB().reset() is called, to eliminate any current output.

getGapsFilledCount

public final int getGapsFilledCount()

How many gaps have been filled so far?

Throws:

AssertException - If isTemplateSet equals false.

getGapsNotYetFilledCount

public final int getGapsNotYetFilledCount()

How many gaps have not yet been filled?

Returns:

(getTemplate().getUSAPUnique().getLength() - getGapsFilledCount())

Throws:

AssertException - If isTemplateSet equals false.

getGapsNotYetFilled

public final String[] getGapsNotYetFilled()

Get a String array containing all unique gap names that have yet to be filled.

Do not call this repeatedly, as it manually creates an array each time. Calling this two times in a row doesn't work?

Returns:

A string array containing all unique gap names that have not yet been filled. If all gaps have been filled, return null.

Throws:

AssertException - If isTemplateSet equals false.

setAllowOWSetInMidFill

public final void setAllowOWSetInMidFill(boolean b_allowSetOWInMidFill)

Declare if it legal to call setOWriter/setOWIntoSB in mid-fill.

Get with doAllowOWSetInMidFill

Parameters:

b_allowSetOWInMidFill - If true, then it is perfectly legal to set a new OWriter, via setOWriter and setOWIntoSB, even in the middle of filling a Template. If false, then it is illegal to do so.

doAllowOWSetInMidFill

public final boolean doAllowOWSetInMidFill()

Is it legal to call setOWriter/setOWIntoSB in mid-fill?

Set with setAllowOWSetInMidFill

Returns:

true If it is perfectly legal to set a new OWriter, via setOWriter and setOWIntoSB, even in the middle of filling a Template.
false If it is illegal to do so.

isOWriterOWIntoSB

public final boolean isOWriterOWIntoSB()

Is the OWriter an OWIntoSB?

Returns:

true Only if you used setOWIntoSB to set the OWriter, or used the non-OWriter constructors of This class.
false If you set an OWriter into setOWriter, or indirectly did so by using the OWriter constructor of this class. Even if you set an OWIntoSB into setOWriter, this will still return false.

getOWriter

public final OWriter getOWriter()

Get the OWriter for direct manipulation.

Set with setOWIntoSB or setOWriter

Returns:

The OWriter as provided to setOWriter or setOWIntoSB.

getOWIntoSB

public final OWIntoSB getOWIntoSB()

Get the OWIntoSB for direct manipulation.

Set with setOWIntoSB or setOWriter

Throws:

AssertException - If getOWriter is of any type except OWIntoSB.

setOWriter

public final void setOWriter(OWriter o_writer)

Set an OWriter into this TemplateFiller.

Get with getOWriter.

This Eliminate the current OWriter, and replaces it with parameter.

Note that calling setOWriter(new OWIntoSB()) is not the same as calling setOWIntoSB. If you do call this function with an OWIntoSB (or any other type), isOWriterOWIntoSB will always return false.

Parameters:

o_writer - The OWriter that will do the outputting of the filled Template text. May not be null.

Throws:

AssertException - If doAllowOWSetInMidFill is false, and you are currently in the middle of filling a Template.

setOWIntoSB

public final void setOWIntoSB()

Eliminate the current OWriter, and replaces it with a new OWIntoSB object.

Get with getOWriter.

OWIntoSB is a special OWriter that stores the resulting output into an internal StringBuffer. This holds the result internally until the getResult function is called.

Note that calling setOWriter(new OWIntoSB()) is not the same as calling this function. If you do call setOWriter with an OWIntoSB (or any other type), isOWriterOWIntoSB will always return false. The only thing that will make it return true is to call this function.

Throws:

AssertException - If doAllowOWSetInMidFill is false, and you are currently in the middle of filling a Template.

getOptrDbg

public final Outputter getOptrDbg()

setOptrDbg

public final void setOptrDbg(Outputter optr_dbg)

dbg

public final void dbg(String s)

dbgnl

public final void dbgnl(String s)