condor.classad
Class ClassAdWriter

Object
  |
  +--Writer
        |
        +--PrintWriter
              |
              +--condor.classad.ClassAdWriter

public class ClassAdWriter
extends PrintWriter

A tool for converting classads to characters in a variety of formats. A ClassAdWriter behaves like a java.io.PrintWriter except that it has two additional methods print(Expr) and println(Expr). An instance has an associated representation and set of options.

Currently, we support three representations:

NATIVE
The "native" ASCII representation, e.g.
    [ my_string = "abc"; my_list = {1, 2, x + 1};]
 
XML
An XML (Extensible Markup Language) representation, e.g.
     <c>
         <a n="my_string"><s>abc</s></a>
         <a n="my_list"><l> <n>1</n> <n>2</n> <e>x+1</e> </l></a>
     </c>
 
The third representation is "OLD" classads, supported only for compatibility with a previous version C++ implementation of classified advertisements. Only RecordExprs can be represented in this format, and the format is inherently binary, requiring a DataOutput. To represent an ad in the OLD format, use RecordExpr.transmit(java.io.DataOutput).

Other external representations may be added in the future.

Options provide finer control over the output format, for example, the native representation may be formatted for readability (e.g. listing each attribute of a RecordExpression on a separate line) or for compactness. By default, a ClassAdWriter uses NATIVE representation and formats the same as Expr.toString() so that code such as

     Expr e = ...;
     ClassAdWriter out = new ClassAdWriter(System.out);
     out.println(e)
 
has the same effect as
     Expr e = ...;
     System.out.println(e);
 
However, a ClassAdWriter allows more control over representation and formatting details. It also may be more efficient for large expressions, since the string representation doesn't need to be assembled in memory before being printed.

Version:
2.0
Author:
Marvin Solomon

Field Summary
static int BRIEF
          A combination of option flags for formatFlags.
static int COMPACT
          A combination of option flags for formatFlags.
static int MINIMAL_PARENTHESES
          An option flag for formatFlags.
static int MULTI_LINE_ADS
          An option flag for formatFlags.
static int MULTI_LINE_LISTS
          An option flag for formatFlags.
static int NATIVE
          Native output representation (e.g.
static int NO_ESCAPE_STRINGS
          An option flag for formatFlags.
static int READABLE
          A combination of option flags for formatFlags.
static int SHOW_ERROR_DETAIL
          An option flag for formatFlags.
static int XML
          XML output representation (e.g.
 
Fields inherited from class PrintWriter
out
 
Fields inherited from class Writer
lock
 
Constructor Summary
ClassAdWriter(OutputStream out)
          Creates a new ClassAdWriter for writing to an existing OutputStream using the NATIVE representation, without automatic line flushing.
ClassAdWriter(OutputStream out, boolean autoFlush)
          Creates a new ClassAdWriter for writing to an existing OutputStream using the NATIVE representation.
ClassAdWriter(OutputStream out, int representation)
          Creates a new ClassAdWriter for writing to an existing OutputStream in a given representation, without automatic line flushing.
ClassAdWriter(OutputStream out, int representation, boolean autoFlush)
          Creates a new ClassAdWriter for writing to an existing OutputStream in a given representation.
ClassAdWriter(Writer out)
          Creates a new ClassAdWriter for writing to an existing Writer using the NATIVE representation, without automatic line flushing.
ClassAdWriter(Writer out, boolean autoFlush)
          Creates a new ClassAdWriter for writing to an existing Writer using the NATIVE representation.
ClassAdWriter(Writer out, int representation)
          Creates a new ClassAdWriter for writing to an existing Writer in a given representation, without automatic line flushing.
ClassAdWriter(Writer out, int representation, boolean autoFlush)
          Creates a new ClassAdWriter for writing to an existing Writer in a given representation.
 
Method Summary
 void close()
          Close this writer.
 void disableFormatFlags(int flags)
          Turn off options for converting expressions to strings.
 void enableFormatFlags(int flags)
          Turn on options for converting expressions to strings.
 int getFormatFlags()
          Get existing options for converting expressions to strings.
 void print(Expr exp)
          Print a classad expression.
 void println(Expr exp)
          Print a classad expression and then terminate the line.
 void setFormatFlags(int flags)
          Set options for converting expressions to strings.
 
Methods inherited from class PrintWriter
checkError, flush, print, print, print, print, print, print, print, print, print, println, println, println, println, println, println, println, println, println, println, setError, write, write, write, write, write
 
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NATIVE

public static final int NATIVE
Native output representation (e.g. [a=x+1]).

See Also:
Constant Field Values

XML

public static final int XML
XML output representation (e.g. <c><a name="a"><e>x+1</e></a></c> ).

See Also:
Constant Field Values

NO_ESCAPE_STRINGS

public static final int NO_ESCAPE_STRINGS
An option flag for formatFlags. Don't surround strings with quotes or escape special characters in the string.

WARNING: Strings created with this flag cannot be parsed to recover the expressions that created them.

See Also:
setFormatFlags(int), Constant Field Values

SHOW_ERROR_DETAIL

public static final int SHOW_ERROR_DETAIL
An option flag for formatFlags. Print the ERROR value as ``ERROR(reason)'' rather than just ``ERROR''.

See Also:
setFormatFlags(int), Constant Field Values

MINIMAL_PARENTHESES

public static final int MINIMAL_PARENTHESES
An option flag for formatFlags. Use only as many parentheses are are required to override the default precendence of operators.

See Also:
setFormatFlags(int), Constant Field Values

MULTI_LINE_ADS

public static final int MULTI_LINE_ADS
An option flag for formatFlags. Display classads with one attribute per line.

See Also:
setFormatFlags(int), Constant Field Values

MULTI_LINE_LISTS

public static final int MULTI_LINE_LISTS
An option flag for formatFlags. Display lists with one member per line.

See Also:
setFormatFlags(int), Constant Field Values

BRIEF

public static final int BRIEF
A combination of option flags for formatFlags. Produce a concise version (both MINIMAL_PARENTHESES and NO_ESCAPE_STRINGS).

See Also:
setFormatFlags(int), MINIMAL_PARENTHESES, NO_ESCAPE_STRINGS, Constant Field Values

COMPACT

public static final int COMPACT
A combination of option flags for formatFlags. Produce a compact but parsable version (currently, the same as MINIMAL_PARENTHESES).

See Also:
setFormatFlags(int), MINIMAL_PARENTHESES, Constant Field Values

READABLE

public static final int READABLE
A combination of option flags for formatFlags. Produce a maximally-readable version (all flags set).

See Also:
setFormatFlags(int), Constant Field Values
Constructor Detail

ClassAdWriter

public ClassAdWriter(OutputStream out,
                     int representation,
                     boolean autoFlush)
Creates a new ClassAdWriter for writing to an existing OutputStream in a given representation. Characters are converted to bytes using the default character encoding.

Parameters:
out - the desitination for output.
representation - the representation (one of NATIVE or XML).
autoFlush - if true, the println() methods will flush the output buffer.

ClassAdWriter

public ClassAdWriter(OutputStream out,
                     int representation)
Creates a new ClassAdWriter for writing to an existing OutputStream in a given representation, without automatic line flushing. Characters are converted to bytes using the default character encoding.

Parameters:
out - the desitination for output.
representation - the representation (one of NATIVE or XML).

ClassAdWriter

public ClassAdWriter(OutputStream out,
                     boolean autoFlush)
Creates a new ClassAdWriter for writing to an existing OutputStream using the NATIVE representation. Characters are converted to bytes using the default character encoding.

Parameters:
out - the desitination for output.
autoFlush - if true, the println() methods will flush the output buffer.

ClassAdWriter

public ClassAdWriter(OutputStream out)
Creates a new ClassAdWriter for writing to an existing OutputStream using the NATIVE representation, without automatic line flushing. Characters are converted to bytes using the default character encoding.

Parameters:
out - the desitination for output.

ClassAdWriter

public ClassAdWriter(Writer out,
                     int representation,
                     boolean autoFlush)
Creates a new ClassAdWriter for writing to an existing Writer in a given representation. Characters are converted to bytes using the default character encoding.

Parameters:
out - the desitination for output.
representation - the representation (one of NATIVE or XML).
autoFlush - if true, the println() methods will flush the output buffer.

ClassAdWriter

public ClassAdWriter(Writer out,
                     int representation)
Creates a new ClassAdWriter for writing to an existing Writer in a given representation, without automatic line flushing. Characters are converted to bytes using the default character encoding.

Parameters:
out - the desitination for output.
representation - the representation (one of NATIVE or XML).

ClassAdWriter

public ClassAdWriter(Writer out,
                     boolean autoFlush)
Creates a new ClassAdWriter for writing to an existing Writer using the NATIVE representation. Characters are converted to bytes using the default character encoding.

Parameters:
out - the desitination for output.
autoFlush - if true, the println() methods will flush the output buffer.

ClassAdWriter

public ClassAdWriter(Writer out)
Creates a new ClassAdWriter for writing to an existing Writer using the NATIVE representation, without automatic line flushing. Characters are converted to bytes using the default character encoding.

Parameters:
out - the desitination for output.
Method Detail

setFormatFlags

public void setFormatFlags(int flags)
Set options for converting expressions to strings.

See Also:
NO_ESCAPE_STRINGS, SHOW_ERROR_DETAIL, MINIMAL_PARENTHESES, MULTI_LINE_ADS, MULTI_LINE_LISTS, BRIEF, COMPACT, READABLE

getFormatFlags

public int getFormatFlags()
Get existing options for converting expressions to strings.

Returns:
the current option flags.
See Also:
NO_ESCAPE_STRINGS, SHOW_ERROR_DETAIL, MINIMAL_PARENTHESES, MULTI_LINE_ADS, MULTI_LINE_LISTS, BRIEF, COMPACT, READABLE

enableFormatFlags

public void enableFormatFlags(int flags)
Turn on options for converting expressions to strings.

See Also:
NO_ESCAPE_STRINGS, SHOW_ERROR_DETAIL, MINIMAL_PARENTHESES, MULTI_LINE_ADS, MULTI_LINE_LISTS, BRIEF, COMPACT, READABLE

disableFormatFlags

public void disableFormatFlags(int flags)
Turn off options for converting expressions to strings.

See Also:
NO_ESCAPE_STRINGS, SHOW_ERROR_DETAIL, MINIMAL_PARENTHESES, MULTI_LINE_ADS, MULTI_LINE_LISTS, BRIEF, COMPACT, READABLE

println

public void println(Expr exp)
Print a classad expression and then terminate the line. This method behaves as though it invokes print(Expr) and then println().

Parameters:
exp - the expression to be printed.

print

public void print(Expr exp)
Print a classad expression.

Parameters:
exp - the expression to be printed.

close

public void close()
Close this writer.

Overrides:
close in class PrintWriter