xbn.output
Class OWFile

java.lang.Object
  |
  +--xbn.XBNObject
        |
        +--xbn.output.OWriter
              |
              +--xbn.output.OWFile

Direct Known Subclasses:

OWSDOAndFile

public class OWFile

extends OWriter

An OWriter where the destination is a file, via java.io.PrintWriter.print/println. For use in Outputter.

Source code: OWFile.java. Example code See the similar example code for OWriter.

You may deactivate or activate this object at any time. When you require a OWFile object, but do not wish to output anything, then create this object as permanently inactive. Although you cannot call the write/debug functions in this condition (errors would be thrown if you try), a permanently inactive OWFile saves memory and processing, because the java.io.PrintWriter is never created.

Fields inherited from class xbn.XBNObject

bFALSE_IN_PRODUCTION, bTRUE_IN_PRODUCTION, sCNSTR, sES, sLINE_SEP

Constructor Summary

OWFile()
Create a "permanently inactive" OWFile object.

OWFile(String s_fileName)
Create a OWFile.

OWFile(String s_fileName, boolean b_append)
Create a OWFile, with the specified name, file name and append configuration.

Method Summary

void	activate() Activate this OWFile.
void	deactivate() Deactivate this OWFile.
protected void	finalize() When this OWFile object is destroyed, this properly deactivates the internal PrintWriter.
String	getPath() Get the full file name.
boolean	isActive() Is this OWFile active?
boolean	isPermanentlyInactive() Is this OWFile permanently inactive?.
boolean	isPotentiallyActive() Is this OWFile potentially active?.
void	newln() Output a newline only, to the file.
String	toString() Get some information about this OWFile object.
void	write(String s_message) Output a line of text to the file with a newline added to the end.
void	writeNoln(String s_message) Output a line of text to the file.

Methods inherited from class xbn.XBNObject

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

Methods inherited from class java.lang.Object

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

Constructor Detail

OWFile

public OWFile()

Create a "permanently inactive" OWFile object. Use this when you require a OWFile object, but do not wish to actually output anything.

When permanently inactive, any call to activate, write or writeNoln will result in an AssertException. However, this allows your write statements to remain in your code, without actually wasting the energy to create the PrintWriter.

OWFile

public OWFile(String s_fileName)

Create a OWFile.

Equal to OWFile(s_fileName, true)

OWFile

public OWFile(String s_fileName,
              boolean b_append)

Create a OWFile, with the specified name, file name and append configuration.

Parameters:

s_fileName - The full directory path and file name. This file must be writeable, but does not have to exist.

b_append - Passed directly to the FileWriter constructor, which is part of making the PrintWriter file pointer. If "true", then existing text remains untouched, and all text written by this object will be appended to the end. If "false", then currently existing text is deleted.

Note that this setting is only applied during the constructor. After this object has been created, if deactivated and then activated again, the newly activated PrintWriter will always append (b_append=true) to the end of any existing text. See activate.

Method Detail

write

public void write(String s_message)

Output a line of text to the file with a newline added to the end.

Overrides:

write in class OWriter

Throws:

AssertException - When this object is inactive.

writeNoln

public void writeNoln(String s_message)

Output a line of text to the file. No newline is added to the end.

Overrides:

writeNoln in class OWriter

Throws:

AssertException - When this object is inactive.

newln

public void newln()

Output a newline only, to the file.

Overrides:

newln in class OWriter

Throws:

AssertException - When this object is inactive.

activate

public final void activate()

Activate this OWFile. Actually creates a "pipeline" (java.io.PrintWriter) to the file--as indicated by getPath, and creates the file if it does not already exist. This is a relatively expensive operation.

Deactivate with deactivate. Get with isActive

Here's what this function actually does:

new PrintWriter(new BufferedWriter(new FileWriter(getPath(), true)))

As indicated by the "true" parameter of the FileWriter constructor, this leaves existing text alone when creating the file pointer. Subsequent text written by this class is concatenated to the end of the file.

In the constructor of this class, it is possible to set the b_append variable to true, which tells the FileWriter that existing text should be deleted before creating the file pointer. Note this is only possible during the constructor. All manual calls to this activate function will set this boolean to true.

Throws:

AssertException - If this object is permanently inactive or already active (isActive is true).

AssertException - If the provided file name is not legal (is not writeable, is bogus, is a directory...). Remember, even if a file is found as legal at one moment--such as when this object was first created, it is possible for the characteristics of that file to be manually changed. Therefore, it is possible for that formerly-legal file to be suddenly illegal at a later time...

NullPointerException - If some other unknown error has occured.

deactivate

public void deactivate()

Deactivate this OWFile. This actually closes and nullifies the java.io.PrintWriter. If already inactive, this does nothing.

Activate with activate. Get with isActive

Continually using deactivate and activate is a relatively expensive operation, and not recommended. Instead of creating a OWFile and then immediately deactivating it (and leaving it that way), consider creating a permanently inactive OWFile instead.

isActive

public boolean isActive()

Is this OWFile active?

Set with activate and deactivate

If permanently inactive, or if you've explicitely called deactivate, this object is inactive.

When inactive, calls to write and writeNoln will result in an AssertException.

Overrides:

isActive in class OWriter

Returns:

true if the object is currently active.
false if the object is currently inactive.

isPotentiallyActive

public final boolean isPotentiallyActive()

Is this OWFile potentially active?. "Potentially active" is the opposite of "permanently inactive".

When potentially active, this object is either currently active, or is activate-able.

If create with any constructor except for the no-parameter constructor, this OWFile is potentially active.

Returns:

true if the object is potentially active.
false if the object is permanently inactive.

isPermanentlyInactive

public final boolean isPermanentlyInactive()

Is this OWFile permanently inactive?. "Permanently inactive" is the opposite of "potentially active"

When permanently inactive, it is not possible to ever activate this OWFile.

When this object was created with the no-parameter constructor, this OWFile is considered permanently inactive. This means that any attempt to use the activate or write/writeNoln functions will result in an error. When your code requires a OWFile object, but no output is desired, a permanently inactive OWFile is what you want. It fulfills your requirements, but does not waste any energy or memory on the PrintWriter.

Returns:

!isPotentallyActive()

finalize

protected void finalize()
                 throws Throwable

When this OWFile object is destroyed, this properly deactivates the internal PrintWriter. See deactivate.

Overrides:

finalize in class Object

getPath

public final String getPath()

Get the full file name.

Returns:

s_fileName Exactly as provided to the constructor, as long as isPotentiallyActive equals true.
null If isPotentiallyActive equals false.

toString

public String toString()

Get some information about this OWFile object.

Overrides:

toString in class Object