XMLDumpContext

java.lang.Object
- arlut.csd.ganymede.server.XMLDumpContext

```
public final class XMLDumpContext
extends java.lang.Object
```
This class is used on the server to group parameters that will guide the server in doing an XML dump.

Field Summary

Fields
Modifier and Type	Field and Description
`private boolean`	`beforeState` If true, this XMLDumpContext is currently writing out the before state of a transaction incremental dump.
`private FieldBook`	`book` If we're doing an incremental sync, we'll use a FieldBook to denote what objects and fields we need to write to this XMLDumpContext.
`private boolean`	`dumpCreatorModifierInfo` If true, the Ganymede server thread using this XMLDumpContext will include the four standard history fields for each object in the emitted XML file.
`private boolean`	`dumpPasswordHashes` If true, the Ganymede server thread using this XMLDumpContext will include password hash information to the emitted XML file.
`private boolean`	`dumpPlaintextPasswords` If true, the Ganymede server thread using this XMLDumpContext will include plaintext passwords to the emitted XML file whenever possible
`private boolean`	`includeOid` If true, this XMLDumpContext will write out oid attributes for dumped objects.
`(package private) int`	`indentLevel`
`private Query`	`query` If non-null, this XMLDumpContext is being used to present the results of a Ganymede `Query` operation to the xmlclient.
`private DBSession`	`session` Reference to a DBSesssion that is used to provide a DBSession context when emitting XML from InvidDBFields from DBObjects that were not edited by a DBSesssion.
`private SyncRunner`	`syncConstraints` If non-null, this SyncRunner will be consulted to answer the mayInclude and shouldInclude questions.
`(package private) XMLWriter`	`xmlOut` The actual writer, from James Clark's XML package.

Constructor Summary

Constructors
Constructor and Description
`XMLDumpContext(XMLWriter xmlOut)` Constructor for use with dumping schema to XML
`XMLDumpContext(XMLWriter xmlOut, boolean passwords, boolean historyInfo, SyncRunner syncConstraints, boolean includeOid)` Main constructor
`XMLDumpContext(XMLWriter xmlOut, Query query)` Constructor for use with dumping query results to XML

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`attribute(java.lang.String name, java.lang.String value)` Writes an attribute.
`void`	`cdataSection(java.lang.String content)` Writes a CDATA section.
`void`	`characterReference(int n)` Writes a character reference.
`void`	`close()` Closes the output stream and clears any DBSession, FieldBook, SyncRunner, or Query linked to this XMLDumpContext.
`void`	`comment(java.lang.String body)` Writes a comment.
`boolean`	`doDumpHistoryInfo()` Returns true if this XMLDumpContext is configured to dump creation and modification information when writing out object records.
`boolean`	`doDumpPasswords()` Returns true if this XMLDumpContext is configured to dump password information of any kind (i.e., password hashes)
`boolean`	`doDumpPlaintext()` Returns true if this XMLDumpContext is configured to dump plaintext password information to disk when a password field has enough information in crypt() or md5Crypt() form that the Ganymede server would be able to load and authenticate against a non-plaintext version of the password.
`void`	`endAttribute()` Ends an attribute.
`void`	`endElement(java.lang.String name)` Ends an element.
`void`	`endElementIndent(java.lang.String name)` Ends an element, indenting before emitting the end tag.
`void`	`endReplacementText()` Ends the replacement text for an internal entity.
`void`	`entityReference(boolean isParam, java.lang.String name)` Writes an entity reference.
`void`	`flush()`
`DBSession`	`getDBSession()`
`int`	`getIndent()` Returns the current indentation level.
`java.lang.String`	`getSyncChannelName()` Returns the name of the Sync Channel we're writing to, if we are writing to one.
`XMLWriter`	`getWriter()`
`void`	`indent()` This helper method writes a newline and the appropriate amount of indentation to this XMLDumpContext's stream.
`void`	`indentIn()` Decreases the indent level one step.
`void`	`indentOut()` Increase the indent level one step.
`boolean`	`isBeforeStateDumping()` Returns true if this XMLDumpContext is writing out the before state of an incremental dump, or false if we're either writing the after state or are not doing an incremental dump.
`boolean`	`isDeltaSyncing()` Returns true if this XMLDumpContext was created to write to a delta sync channel.
`boolean`	`isDumpingOid()` This method returns true if this XMLDumpContext wants to include oid attributes in dumped objects.
`boolean`	`isSyncing()` Returns true if this XMLDumpContext was created to write to a sync channel.
`void`	`markup(java.lang.String str)` Writes markup.
`boolean`	`mayInclude(DBField field)` Returns true if the kind of DBField passed in needs to be synced in the context of a query or sync channel attached to this XMLDumpContext.
`boolean`	`mayInclude(DBField field, boolean hasChanged)` Returns true if the kind of DBField passed in needs to be synced to the sync channel attached to this XMLDumpContext.
`boolean`	`mayInclude(DBObject object)` Returns true if the DBObject passed in needs to be synced to this channel.
`void`	`processingInstruction(java.lang.String target, java.lang.String data)` Writes a processing instruction.
`void`	`setBeforeStateDumping(boolean param)` Sets whether or not this XMLDumpContext is in the middle of writing out the before state of an incremental dump.
`void`	`setDBSession(DBSession session)`
`void`	`setDeltaFieldBook(FieldBook book)` Associates a FieldBook with this XMLDumpContext.
`void`	`setDumpPasswords(boolean allowHashes)` Sets whether an XML Query being processed by this XMLDumpContext should allow password field hashes to be transmitted.
`void`	`setIndentLevel(int x)` This method directly sets the indention level for subsequent indent(), startElementIndent(), and endElementIndent() calls.
`boolean`	`shouldInclude(DBEditObject object)` Returns true if the DBEditObject passed in needs to be synced to the sync channel we're writing to.
`boolean`	`shouldInclude(DBField newField, DBField oldField)` Returns true if the given field needs to be sent to this sync channel.
`void`	`skipLine()`
`void`	`startAttribute(java.lang.String name)` Starts an attribute.
`void`	`startElement(java.lang.String name)` Starts an element.
`void`	`startElementIndent(java.lang.String name)` Starts an element, preceded by a newline and indented according to the current indent level.
`void`	`startReplacementText()` Starts the replacement text for an internal entity.
`void`	`write(java.lang.String str)`
`XMLWriter`	`writer()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - dumpPasswordHashes
```
private boolean dumpPasswordHashes
```
    If true, the Ganymede server thread using this XMLDumpContext will include password hash information to the emitted XML file.
    
    If false, no password hash data will be emitted at all.
  - dumpPlaintextPasswords
```
private boolean dumpPlaintextPasswords
```
    If true, the Ganymede server thread using this XMLDumpContext will include plaintext passwords to the emitted XML file whenever possible
  - dumpCreatorModifierInfo
```
private boolean dumpCreatorModifierInfo
```
    If true, the Ganymede server thread using this XMLDumpContext will include the four standard history fields for each object in the emitted XML file.
  - syncConstraints
```
private SyncRunner syncConstraints
```
    If non-null, this SyncRunner will be consulted to answer the mayInclude and shouldInclude questions.
    
    syncConstraints will be null if we are doing a non-sync channel filtered dump from the DBStore using the xmlclient.
    
    If we're using this XMLDumpContext to do a sync, or we're using xmlclient with a channel specified, syncConstraints will help us figure out what specific data we need to dump.
  - book
```
private FieldBook book
```
    If we're doing an incremental sync, we'll use a FieldBook to denote what objects and fields we need to write to this XMLDumpContext.
    
    If book is non-null, this XMLDumpContext is being used to transmit a transaction delta, in which case we'll want to let callers know so that they can decide to handle certain things (such as embedded objects) differently.
  - session
```
private DBSession session
```
    Reference to a DBSesssion that is used to provide a DBSession context when emitting XML from InvidDBFields from DBObjects that were not edited by a DBSesssion.
  - beforeState
```
private boolean beforeState
```
    If true, this XMLDumpContext is currently writing out the before state of a transaction incremental dump. We'll keep hold of this information so server-side code can decide whether to write information from the before or after state of a transaction in progress.
    
    If we're not dumping out a transactional incremental dump, this variable should always be false.
  - includeOid
```
private boolean includeOid
```
    If true, this XMLDumpContext will write out oid attributes for dumped objects.
  - query
```
private Query query
```
    If non-null, this XMLDumpContext is being used to present the results of a Ganymede Query operation to the xmlclient. When DBObjects are dumped to this XMLDumpContext in such a case, the fields included in the dump will be filtered against the fields requested in this Query object.
  - xmlOut
```
XMLWriter xmlOut
```
    The actual writer, from James Clark's XML package.
  - indentLevel
```
int indentLevel
```
- Constructor Detail
  - XMLDumpContext
```
public XMLDumpContext(XMLWriter xmlOut)
```
    Constructor for use with dumping schema to XML
    
    Parameters:
    xmlOut - The XMLWriter to write to
  - XMLDumpContext
```
public XMLDumpContext(XMLWriter xmlOut,
              Query query)
```
    Constructor for use with dumping query results to XML
    
    Parameters:
    xmlOut - The XMLWriter to write to
    query - The Query object defining the fields to include
  - XMLDumpContext
```
public XMLDumpContext(XMLWriter xmlOut,
              boolean passwords,
              boolean historyInfo,
              SyncRunner syncConstraints,
              boolean includeOid)
```
    Main constructor
    
    Parameters:
    xmlOut - The XMLWriter to write to
    passwords - Include plaintext passwords in password field dumps, even if the password field includes UNIX crypt() or md5Crypt() passwords that could be depended on for authentication without having to reveal the plaintext.
    historyInfo - If true, all objects dumped out using this XMLDumpContext will include creator and modification information.
    syncConstraints - If non-null, this XMLDumpContext will carry along with it enough information to answer questions about whether a given object or field should be emitted to the Sync Channel this XMLDumpContext is writing to. If null, the mayInclude and shouldInclude methods will always return true.
    includeOid - If true, the objects written out to the xml stream will include an "oid" attribute which contains the precise Invid of the object.
- Method Detail
  - getWriter
```
public XMLWriter getWriter()
```
  - writer
```
public XMLWriter writer()
```
  - isSyncing
```
public boolean isSyncing()
```
    Returns true if this XMLDumpContext was created to write to a sync channel.
  - setDeltaFieldBook
```
public void setDeltaFieldBook(FieldBook book)
```
    Associates a FieldBook with this XMLDumpContext.
    
    If the book param is non-null, we will use it to decide what objects and fields need to be written out.
    
    A non-null book parameter will configure this XMLDumpContext for delta syncing, and isDeltaSyncing() will return true thereafter.
  - setDBSession
```
public void setDBSession(DBSession session)
```
  - getDBSession
```
public DBSession getDBSession()
```
  - isDeltaSyncing
```
public boolean isDeltaSyncing()
```
    Returns true if this XMLDumpContext was created to write to a delta sync channel.
  - setBeforeStateDumping
```
public void setBeforeStateDumping(boolean param)
```
    Sets whether or not this XMLDumpContext is in the middle of writing out the before state of an incremental dump.
  - isBeforeStateDumping
```
public boolean isBeforeStateDumping()
```
    Returns true if this XMLDumpContext is writing out the before state of an incremental dump, or false if we're either writing the after state or are not doing an incremental dump.
  - isDumpingOid
```
public boolean isDumpingOid()
```
    This method returns true if this XMLDumpContext wants to include oid attributes in dumped objects. This will ultimately be true when the -includeOid command line flag is set on the xmlclient, or when the server is dumping to a sync channel.
  - getSyncChannelName
```
public java.lang.String getSyncChannelName()
```
    Returns the name of the Sync Channel we're writing to, if we are writing to one.
  - mayInclude
```
public boolean mayInclude(DBObject object)
```
    Returns true if the DBObject passed in needs to be synced to this channel. This version of shouldInclude() assumes that the object passed in is a read-only DBObject. In this case, the shouldInclude() test will just determine whether an object of this type should ever be written to the sync channel we are writing to, if indeed we are writing to one. If we're not writing to a sync channel, this method always returns true.
  - shouldInclude
```
public boolean shouldInclude(DBEditObject object)
```
    Returns true if the DBEditObject passed in needs to be synced to the sync channel we're writing to. Because we're passed in a DBEditObject, we can assume that we are being asked about whether we should write out this object in the course of a sync operation. When DBStore is writing out an XML dump, all the objects should be read only copies, so we will always use the DBObject version of shouldInclude().
    
    If we're not writing to a sync channel, this method always returns true.
  - shouldInclude
```
public boolean shouldInclude(DBField newField,
                    DBField oldField)
```
    Returns true if the given field needs to be sent to this sync channel. This method is responsible for doing the determination only if both field and origField are not null and isDefined().
    
    If we're not writing to a sync channel, this method always returns true.
  - mayInclude
```
public boolean mayInclude(DBField field)
```
    Returns true if the kind of DBField passed in needs to be synced in the context of a query or sync channel attached to this XMLDumpContext. This version of mayInclude() treats the field as always changed, and is intended for doing queries and full state syncs / dumps, and not delta dumps.
    
    This differs from shouldInclude on DBField in that this method leaves it to the caller to decide whether the field has changed.
    
    If we're not writing to a sync channel, this method always returns true.
  - mayInclude
```
public boolean mayInclude(DBField field,
                 boolean hasChanged)
```
    Returns true if the kind of DBField passed in needs to be synced to the sync channel attached to this XMLDumpContext. The hasChanged parameter should be set to true if the field being tested was changed in the current transaction, or false if it remains unchanged.
    
    This differs from shouldInclude on DBField in that this method leaves it to the caller to decide whether the field has changed.
    
    If we're not writing to a sync channel, this method always returns true.
  - indentOut
```
public void indentOut()
```
    Increase the indent level one step. Successive indent(), startElementIndent(), and endElementIndent() method calls will indent one level further.
    
    This method itself produces no output.
  - indentIn
```
public void indentIn()
```
    Decreases the indent level one step. Successive indent(), startElementIndent(), and endElementIndent() method calls will decrease one level fiewer.
    
    This method itself produces no output.
  - setIndentLevel
```
public void setIndentLevel(int x)
```
    This method directly sets the indention level for subsequent indent(), startElementIndent(), and endElementIndent() calls.
  - getIndent
```
public int getIndent()
```
    Returns the current indentation level.
  - indent
```
public void indent()
            throws java.io.IOException
```
    This helper method writes a newline and the appropriate amount of indentation to this XMLDumpContext's stream.
    
    Throws:
    
    java.io.IOException
  - skipLine
```
public void skipLine()
              throws java.io.IOException
```
    Throws:
    
    java.io.IOException
  - setDumpPasswords
```
public void setDumpPasswords(boolean allowHashes)
```
    Sets whether an XML Query being processed by this XMLDumpContext should allow password field hashes to be transmitted.
    
    Will be set to false by the XMLTransmitter constructor if the controlling GanymedeSession is not supergash.
  - doDumpPasswords
```
public boolean doDumpPasswords()
```
    Returns true if this XMLDumpContext is configured to dump password information of any kind (i.e., password hashes)
  - doDumpPlaintext
```
public boolean doDumpPlaintext()
```
    Returns true if this XMLDumpContext is configured to dump plaintext password information to disk when a password field has enough information in crypt() or md5Crypt() form that the Ganymede server would be able to load and authenticate against a non-plaintext version of the password.
  - doDumpHistoryInfo
```
public boolean doDumpHistoryInfo()
```
    Returns true if this XMLDumpContext is configured to dump creation and modification information when writing out object records.
  - startElementIndent
```
public void startElementIndent(java.lang.String name)
                        throws java.io.IOException
```
    Starts an element, preceded by a newline and indented according to the current indent level. This may be followed by zero or more calls to attribute. The start-tag will be closed by the first following call to any method other than attribute.
    
    Throws:
    
    java.io.IOException
  - startElement
```
public void startElement(java.lang.String name)
                  throws java.io.IOException
```
    Starts an element.
    
    This may be followed by zero or more calls to attribute. The start-tag will be closed by the first following call to any method other than attribute.
    
    Throws:
    
    java.io.IOException
  - attribute
```
public void attribute(java.lang.String name,
             java.lang.String value)
               throws java.io.IOException
```
    Writes an attribute.
    
    This is not legal if there have been calls to methods other than attribute since the last call to startElement, unless inside a startAttribute, endAttribute pair.
    
    Throws:
    
    java.io.IOException
  - startAttribute
```
public void startAttribute(java.lang.String name)
                    throws java.io.IOException
```
    Starts an attribute.
    
    This writes the attribute name, = and the opening quote. This provides an alternative to attribute that allows markup to be included in the attribute value. The value of the attribute is written using the normal write methods; endAttribute must be called at the end of the attribute value. Entity and character references can be written using entityReference and characterReference.
    
    Throws:
    
    java.io.IOException
  - endAttribute
```
public void endAttribute()
                  throws java.io.IOException
```
    Ends an attribute.
    
    This writes the closing quote of the attribute value.
    
    Throws:
    
    java.io.IOException
  - endElementIndent
```
public void endElementIndent(java.lang.String name)
                      throws java.io.IOException
```
    Ends an element, indenting before emitting the end tag.
    
    If the element comprised no content between the startElement and endElement calls, aside from attributes, then endElement should be used. endElementIndent() will always put space between a start and end tag. This may output an end-tag or close the current start-tag as an empty element.
    
    Throws:
    
    java.io.IOException
  - endElement
```
public void endElement(java.lang.String name)
                throws java.io.IOException
```
    Ends an element.
    
    This may output an end-tag or close the current start-tag as an empty element.
    
    Throws:
    
    java.io.IOException
  - processingInstruction
```
public void processingInstruction(java.lang.String target,
                         java.lang.String data)
                           throws java.io.IOException
```
    Writes a processing instruction.
    
    If data is non-empty a space will be inserted automatically to separate it from the target.
    
    Throws:
    
    java.io.IOException
  - comment
```
public void comment(java.lang.String body)
             throws java.io.IOException
```
    Writes a comment.
    
    Throws:
    
    java.io.IOException
  - entityReference
```
public void entityReference(boolean isParam,
                   java.lang.String name)
                     throws java.io.IOException
```
    Writes an entity reference.
    
    Throws:
    
    java.io.IOException
  - characterReference
```
public void characterReference(int n)
                        throws java.io.IOException
```
    Writes a character reference.
    
    Throws:
    
    java.io.IOException
  - cdataSection
```
public void cdataSection(java.lang.String content)
                  throws java.io.IOException
```
    Writes a CDATA section.
    
    Throws:
    
    java.io.IOException
  - startReplacementText
```
public void startReplacementText()
                          throws java.io.IOException
```
    Starts the replacement text for an internal entity.
    
    The replacement text must be ended with endReplacementText. This enables an extra level of escaping that protects against the process of constructing an entity's replacement text from the literal entity value. See Section 4.5 of the XML Recommendation. Between a call to startReplacementText and endReplacementText, the argument to markup would specify entity replacement text; these would be escaped so that when processed as a literal entity value, the specified entity replacement text would be constructed.
    
    This call does not itself cause anything to be written.
    
    Throws:
    
    java.io.IOException
  - endReplacementText
```
public void endReplacementText()
                        throws java.io.IOException
```
    Ends the replacement text for an internal entity.
    
    This disables the extra level of escaping enabled by startReplacementText.
    
    This call does not itself cause anything to be written.
    
    Throws:
    
    java.io.IOException
  - markup
```
public void markup(java.lang.String str)
            throws java.io.IOException
```
    Writes markup.
    
    The characters in the string will be written as is without being escaped (except for any escaping enabled by startReplacementText).
    
    Throws:
    
    java.io.IOException
  - write
```
public void write(java.lang.String str)
           throws java.io.IOException
```
    Throws:
    
    java.io.IOException
  - flush
```
public void flush()
           throws java.io.IOException
```
    Throws:
    
    java.io.IOException
  - close
```
public void close()
           throws java.io.IOException
```
    Closes the output stream and clears any DBSession, FieldBook, SyncRunner, or Query linked to this XMLDumpContext.
    
    Throws:
    
    java.io.IOException

Class XMLDumpContext

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

dumpPasswordHashes

dumpPlaintextPasswords

dumpCreatorModifierInfo

syncConstraints

book

session

beforeState

includeOid

query

xmlOut

indentLevel

Constructor Detail

XMLDumpContext

XMLDumpContext

XMLDumpContext

Method Detail

getWriter

writer

isSyncing

setDeltaFieldBook

setDBSession

getDBSession

isDeltaSyncing

setBeforeStateDumping

isBeforeStateDumping

isDumpingOid

getSyncChannelName

mayInclude

shouldInclude

shouldInclude

mayInclude

mayInclude

indentOut

indentIn

setIndentLevel

getIndent

indent

skipLine

setDumpPasswords

doDumpPasswords

doDumpPlaintext

doDumpHistoryInfo

startElementIndent

startElement

attribute

startAttribute

endAttribute

endElementIndent

endElement

processingInstruction

comment

entityReference

characterReference

cdataSection

startReplacementText

endReplacementText

markup

write

flush

close