org.tmatesoft.svn.core.io.diff

## Class SVNDiffWindow

- java.lang.Object
- - org.tmatesoft.svn.core.io.diff.SVNDiffWindow

-     public class SVNDiffWindow
      extends java.lang.Object

  The SVNDiffWindow class represents a diff window that contains instructions and new data of a delta to apply to a file.

  Instructions are not immediately contained in a window. A diff window provides an iterator that reads and constructs one SVNDiffInstruction from provided raw bytes per one iteration. There is even an ability to use a single SVNDiffInstruction object for read and decoded instructions: for subsequent iterations an iterator simply uses the same instruction object to return as a newly read and decoded instruction.

  Since:
    1.2
  Version:
    1.3
  Author:
    TMate Software Ltd.
  See Also:
    `SVNDiffInstruction`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static SVNDiffWindow` | `EMPTY` An empty window (in particular, its instructions length = 0).
    `static byte[]` | `SVN_HEADER` Bytes of the delta header of an uncompressed diff window.
    `static byte[]` | `SVN1_HEADER` Bytes of the delta header of a compressed diff window.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SVNDiffWindow(long sourceViewOffset, int sourceViewLength, int targetViewLength, int instructionsLength, int newDataLength)` Constructs an SVNDiffWindow object.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `apply(byte[] sourceBuffer, byte[] targetBuffer)` Applies this window's instructions provided source and target view buffers.
    `void` | `apply(SVNDiffWindowApplyBaton applyBaton)` Applies this window's instructions.
    `SVNDiffWindow` | `clone(java.nio.ByteBuffer targetData)` Creates an exact copy of this window object.
    `int` | `getDataLength()` Returns the total amount of new data and instruction bytes.
    `int` | `getInstructionsCount()` Returns the amount of instructions of this window object.
    `int` | `getInstructionsLength()` Returns the length of instructions in bytes.
    `int` | `getNewDataLength()` Returns the number of new data bytes to copy to the target view.
    `int` | `getSourceViewLength()` Returns the number of bytes to copy from the source view to the target one.
    `long` | `getSourceViewOffset()` Returns the source view offset.
    `int` | `getTargetViewLength()` Returns the length in bytes of the target view.
    `boolean` | `hasCopyFromSourceInstructions()` Tells whether this window contains any copy-from-source instructions.
    `boolean` | `hasInstructions()` Tells if this window is not empty, i.e. has got any instructions.
    `java.util.Iterator` | `instructions()` Returns an iterator to read instructions in series.
    `java.util.Iterator` | `instructions(boolean template)` Returns an iterator to read instructions in series.
    `SVNDiffInstruction[]` | `loadDiffInstructions(SVNDiffInstruction[] target)` Returns an array of instructions of this window.
    `void` | `setData(java.nio.ByteBuffer buffer)` Sets a byte buffer containing instruction and new data bytes of this window.
    `java.lang.String` | `toString()` Gives a string representation of this object.
    `void` | `writeNewData(java.nio.ByteBuffer target, int offset, int length)` Fills a target buffer with the specified number of new data bytes of this window object taken at the specified offset.
    `void` | `writeTo(java.io.OutputStream os, boolean writeHeader)` Writes this window object to the provided stream.
    `void` | `writeTo(java.io.OutputStream os, boolean writeHeader, boolean compress)` Formats and writes this window bytes to the specified output stream.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### SVN_HEADER

          public static final byte[] SVN_HEADER

      Bytes of the delta header of an uncompressed diff window.

    - #### SVN1_HEADER

          public static final byte[] SVN1_HEADER

      Bytes of the delta header of a compressed diff window.
      Since:
        1.1, new in Subversion 1.4

    - #### EMPTY

          public static final SVNDiffWindow EMPTY

      An empty window (in particular, its instructions length = 0). Corresponds to the case of an empty delta, so, it's passed to a delta consumer to create an empty file.

  - ### Constructor Detail

    - #### SVNDiffWindow

          public SVNDiffWindow(long sourceViewOffset,
                       int sourceViewLength,
                       int targetViewLength,
                       int instructionsLength,
                       int newDataLength)

      Constructs an SVNDiffWindow object. This constructor is used when bytes of instructions are not decoded and converted to SVNDiffInstruction objects yet, but are kept elsewhere along with new data.
      Parameters:
        `sourceViewOffset` - an offset in the source view
        `sourceViewLength` - a number of bytes to read from the source view
        `targetViewLength` - a length in bytes of the target view it must have after copying bytes
        `instructionsLength` - a number of instructions bytes
        `newDataLength` - a number of bytes of new data
      See Also:
        `SVNDiffInstruction`

  - ### Method Detail

    - #### getInstructionsLength

          public int getInstructionsLength()

      Returns the length of instructions in bytes.
      Returns:
        a number of instructions bytes

    - #### getSourceViewOffset

          public long getSourceViewOffset()

      Returns the source view offset.
      Returns:
        an offset in the source from where the source bytes must be copied

    - #### getSourceViewLength

          public int getSourceViewLength()

      Returns the number of bytes to copy from the source view to the target one.
      Returns:
        a number of source bytes to copy

    - #### getTargetViewLength

          public int getTargetViewLength()

      Returns the length in bytes of the target view. The length of the target view is actually the number of bytes that should be totally copied by all the instructions of this window.
      Returns:
        a length in bytes of the target view

    - #### getNewDataLength

          public int getNewDataLength()

      Returns the number of new data bytes to copy to the target view.
      Returns:
        a number of new data bytes

    - #### instructions

          public java.util.Iterator instructions()

      Returns an iterator to read instructions in series. Objects returned by an iterator's `next()` method are separate SVNDiffInstruction objects.

      Instructions as well as new data are read from a byte buffer that is passed to this window object via the `setData()` method.

      A call to this routine is equivalent to a call `instructions(false)`.

      Returns:
        an instructions iterator
      See Also:
        `instructions(boolean)`, `SVNDiffInstruction`

    - #### instructions

          public java.util.Iterator instructions(boolean template)

      Returns an iterator to read instructions in series.

      If `template` is true then each instruction returned by the iterator is actually the same SVNDiffInstruction object, but with proper options. This prevents from allocating new memory.

      On the other hand, if `template` is false then the iterator returns a new allocated SVNDiffInstruction object per each instruction read and decoded.

      Instructions as well as new data are read from a byte buffer that is passed to this window object via the `setData()` method.

      Parameters:
        `template` - to use a single/multiple instruction objects
      Returns:
        an instructions iterator
      See Also:
        `instructions()`, `SVNDiffInstruction`

    - #### apply

          public void apply(SVNDiffWindowApplyBaton applyBaton)
                     throws SVNException

      Applies this window's instructions. The source and target streams are provided by `applyBaton`.

      If this window has got any `SVNDiffInstruction.COPY_FROM_SOURCE` instructions, then:

      1. At first copies a source view from the source stream of `applyBaton` to the baton's inner source buffer. `SVNDiffInstruction.COPY_FROM_SOURCE` instructions of this window are relative to the bounds of that source buffer (source view, in other words).
      2. Second, according to instructions, copies source bytes from the source buffer to the baton's target buffer (or target view, in other words).
      3. Then, if `applyBaton` is supplied with an MD5 digest, updates it with those bytes in the target buffer. So, after instructions applying completes, it will be the checksum for the full text expanded.
      4. The last step - appends the target buffer bytes to the baton's target stream.

      `SVNDiffInstruction.COPY_FROM_NEW_DATA` instructions rule to copy bytes from the instructions & new data buffer provided to this window object via a call to the `setData()` method.

      `SVNDiffInstruction.COPY_FROM_TARGET` instructions are relative to the bounds of the target buffer.

      Parameters:
        `applyBaton` - a baton that provides the source and target views as well as holds the source and targed streams
      Throws:
        `SVNException`
      See Also:
        `apply(byte[], byte[])`

    - #### apply

          public int apply(byte[] sourceBuffer,
                  byte[] targetBuffer)

      Applies this window's instructions provided source and target view buffers.

      If this window has got any `SVNDiffInstruction.COPY_FROM_SOURCE` instructions, then appropriate bytes described by such an instruction are copied from the `sourceBuffer` to the `targetBuffer`.

      `SVNDiffInstruction.COPY_FROM_NEW_DATA` instructions rule to copy bytes from the instructions & new data buffer provided to this window object via a call to the `setData()` method.

      `SVNDiffInstruction.COPY_FROM_TARGET` instructions are relative to the bounds of the `targetBuffer` itself.

      Parameters:
        `sourceBuffer` - a buffer containing a source view
        `targetBuffer` - a buffer to get a target view
      Returns:
        the size of the resultant target view
      See Also:
        `apply(SVNDiffWindowApplyBaton)`

    - #### setData

          public void setData(java.nio.ByteBuffer buffer)

      Sets a byte buffer containing instruction and new data bytes of this window.

      Instructions will go before new data within the buffer and should start at `buffer.position() + buffer.arrayOffset()`.

      Applying a diff window prior to setting instruction and new data bytes may cause a NPE.

      Parameters:
        `buffer` - an input data buffer

    - #### toString

          public java.lang.String toString()

      Gives a string representation of this object.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        a string representation of this object

    - #### hasInstructions

          public boolean hasInstructions()

      Tells if this window is not empty, i.e. has got any instructions.
      Returns:
        true if has instructions, false if has not

    - #### writeTo

          public void writeTo(java.io.OutputStream os,
                     boolean writeHeader)
                       throws java.io.IOException

      Writes this window object to the provided stream.

      If `writeHeader` is true then writes `SVN_HEADER` bytes also.

      Parameters:
        `os` - an output stream to write to
        `writeHeader` - controls whether the header should be written or not
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### writeTo

          public void writeTo(java.io.OutputStream os,
                     boolean writeHeader,
                     boolean compress)
                       throws java.io.IOException

      Formats and writes this window bytes to the specified output stream.
      Parameters:
        `os` - an output stream to write the window to
        `writeHeader` - if true a window header will be also written
        `compress` - if true writes compressed window bytes using `SVN1_HEADER` to indicate that (if `writeHeader` is true), otherwise non-compressed window is written with `SVN_HEADER` (again if `writeHeader` is true)
      Throws:
        `java.io.IOException`
      Since:
        1.1

    - #### getDataLength

          public int getDataLength()

      Returns the total amount of new data and instruction bytes.
      Returns:
        new data length + instructions length

    - #### hasCopyFromSourceInstructions

          public boolean hasCopyFromSourceInstructions()

      Tells whether this window contains any copy-from-source instructions.
      Returns:
        true if this window has got at least one `SVNDiffInstruction.COPY_FROM_SOURCE` instruction

    - #### clone

          public SVNDiffWindow clone(java.nio.ByteBuffer targetData)

      Creates an exact copy of this window object.

      `targetData` is written instruction & new data bytes and then is set to a new window object via a call to its `setData()` method.

      Parameters:
        `targetData` - a byte buffer to receive a copy of this wondow data
      Returns:
        a new window object that is an exact copy of this one

    - #### loadDiffInstructions

          public SVNDiffInstruction[] loadDiffInstructions(SVNDiffInstruction[] target)

      Returns an array of instructions of this window.

      If `target` is large enough to receive all instruction objects, then it's simply filled up to the end of instructions. However if it's not, it will be expanded to receive all instructions.

      Parameters:
        `target` - an instructions receiver
      Returns:
        an array containing all instructions

    - #### getInstructionsCount

          public int getInstructionsCount()

      Returns the amount of instructions of this window object.
      Returns:
        a total number of instructions

    - #### writeNewData

          public void writeNewData(java.nio.ByteBuffer target,
                          int offset,
                          int length)

      Fills a target buffer with the specified number of new data bytes of this window object taken at the specified offset.
      Parameters:
        `target` - a buffer to copy to
        `offset` - an offset relative to the position of the first new data byte of this window object
        `length` - a number of new data bytes to copy

Copyright © 2004-2009 TMate Software Ltd. All Rights Reserved.