JavaSVN Home

## org.tmatesoft.svn.core.io.diff
Class SVNDiffWindowBuilder

    java.lang.Object
      org.tmatesoft.svn.core.io.diff.SVNDiffWindowBuilder

public class SVNDiffWindowBuilder
extends Object

The SVNDiffWindowBuilder class is used to build diff windows from the raw delta data.

The process of restoring a diff window from raw delta data is represented by the following steps:

- reading the header of the delta data; this step is represented by the state `HEADER` of this object;
- reading offsets for a diff window, now they are 5 and include: a source view offset, a source view length, a target view length, instructions length, new data length; this step is represented by the step `OFFSET` of this object;
- reading instructions bytes, parsing, decoding and converting them to SVNDiffInstruction objects; this step is represented by the state `INSTRUCTIONS` of this object;
- after successful reading instructions data the builder is set to the state `DONE` - the diff window is built and may be got via calling `getDiffWindow()`.

Building a diff window:

When a builder is set to the `HEADER` state, at the first calling to a diff window restoring method - accept() - the builder tries to read a header. If header bytes are valid, the builder resets itself to the state `OFFSET`.

At the second call to the accept() method the builder tries to read offsets & lengths, and if succeeds, it resets to the `INSTRUCTIONS` state.

At the next call it reads instructions bytes, but does not convert them to SVNDiffInstruction objects. So, the window being produced would not hold instruction objects but only instructions length, - this is done for memory economy, cause, for example, for large binary files (tens of Mbs) there could be several hundreds of windows and tens of thousands of instructions per window what may cause an out of memory exception. When applying a diff window with the `SVNDiffWindow.apply()` method, the method itself will restore diff instructions from the raw instructions data that must be concatenated with the new data provided to the apply method. But if you need to manually create diff instructions for the produced window, use the `createInstructions()` method.

At last, if instructions have been read successfully, the builder resets to the `DONE` state.

Version:
  1.0
Author:
  TMate Software Ltd.
See Also:
  `SVNDiffWindow`, `SVNDiffInstruction`

Field Summary
`static int` `DONE` The state of this object that denotes that the current diff window is built, and should be taken back via calling `getDiffWindow()`.
`static int` `HEADER` The initial state of this object when it's created.
`static int` `INSTRUCTIONS` The state of this object that denotes that diff window instructions are to be read.
`static int` `OFFSET` The state of this object that denotes that diff window offsets are to be read.

Method Summary
`int` `accept(byte[] bytes, int offset)` Builds a diff window from raw delta bytes.
`boolean` `accept(InputStream is, ISVNEditor consumer, String path)` Builds a diff window/windows from raw delta bytes.
`static SVNDiffInstruction[]` `createInstructions(byte[] bytes)` Parses, decodes the raw instructions bytes and converts them to diff instruction objects.
`static SVNDiffWindow` `createReplacementDiffWindow(long dataLength)` Creates a diff window intended for replacing the whole contents of a file with new data.
`static SVNDiffWindow[]` `createReplacementDiffWindows(long dataLength, int maxWindowLength)` Creates a diff window/windows intended for replacing the whole contents of a file with new data.
`SVNDiffWindow` `getDiffWindow()` Returns the built diff window.
`byte[]` `getInstructionsData()` Returns the raw instructions data of the current diff window.
`boolean` `isBuilt()` Says if the current diff window is built.
`static SVNDiffWindowBuilder` `newInstance()` Creates a new diff window builder.
`void` `reset()` Resets this builder to the initial state - `HEADER`, that is the very beginning of the raw diff window, its header, is expected.
`void` `reset(int state)` Resets this builder to a particular state.
`static void` `save(SVNDiffWindow window, boolean saveHeader, OutputStream os)` Writes the given diff window to the provided output stream as raw delta bytes.

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

Field Detail

### HEADER

    public static final int HEADER

  The initial state of this object when it's created. Denotes that the header of the diff window is to be read.

  See Also:
    Constant Field Values

### OFFSET

    public static final int OFFSET

  The state of this object that denotes that diff window offsets are to be read.

  See Also:
    Constant Field Values

### INSTRUCTIONS

    public static final int INSTRUCTIONS

  The state of this object that denotes that diff window instructions are to be read.

  See Also:
    Constant Field Values

### DONE

    public static final int DONE

  The state of this object that denotes that the current diff window is built, and should be taken back via calling `getDiffWindow()`.

  See Also:
    Constant Field Values

Method Detail

### newInstance

    public static SVNDiffWindowBuilder newInstance()

  Creates a new diff window builder.

  Returns:
    a new builder

### reset

    public void reset()

  Resets this builder to the initial state - `HEADER`, that is the very beginning of the raw diff window, its header, is expected. When calling a diff window restoring method - accept() - it tries to read a header. If header bytes are valid, the builder resets itself to the state `OFFSET`.

  Remember that the inner state of the builder including the produced diff window and its raw instructions data are lost after resetting the builder.

  See Also:
    `reset(int)`

### reset

    public void reset(int state)

  Resets this builder to a particular state.

  Remember that the inner state of the builder including the produced diff window and its raw instructions data are lost after resetting the builder.

  Parameters:
    `state` - one of the four defined state constants

### isBuilt

    public boolean isBuilt()

  Says if the current diff window is built. Get the restored window via a call to `getDiffWindow()`.

  Returns:
    true if the diff window is built, otherwise false

### getDiffWindow

    public SVNDiffWindow getDiffWindow()

  Returns the built diff window.

  Returns:
    a diff window

### getInstructionsData

    public byte[] getInstructionsData()

  Returns the raw instructions data of the current diff window.

  Returns:
    instructions bytes or null if they have not been read

### accept

    public int accept(byte[] bytes,
                      int offset)

  Builds a diff window from raw delta bytes. If every step of restoring a diff window succeeds, the builder automatically resets to the next state (up to the `DONE` state) and recursively calls this method to perform the next step of restoring the window. When this method returns, check if the diff window is completed by `isBuilt()`.

  If the raw delta data also includes new data, the return offset will be the offset where this data begins in the provided buffer.

  If the `bytes` array is not exhausted (i.e. contains more than just one window), you should obtain the produced window, manually reset the builder to the `OFFSET` state and call this accept() method again for building the next window.

  Actually, diff windows created by the SVNDiffWindowBuilder builders are not supplied with diff instructions, use `createInstructions()` to manually create them.

  Parameters:
    `bytes` - raw delta bytes (header, offsets&lengths, instructions, new data, ...)
    `offset` - an offset in the raw delta bytes array, that marks the position from where the bytes are to be read;
  Returns:
    an offset in the raw delta bytes array after reading a sequence of bytes
  See Also:
    `accept(InputStream, ISVNEditor, String)`

### accept

    public boolean accept(InputStream is,
                          ISVNEditor consumer,
                          String path)
                   throws SVNException

  Builds a diff window/windows from raw delta bytes. For every successful step of restoring a diff window, the builder automatically resets to the next state (up to the `DONE` state) and returns true.

  `consumer` is used to collect diff windows and provide output streams to write raw instructions and new data to for each window.

  Actually, diff windows created by the SVNDiffWindowBuilder builders are not supplied with diff instructions, use `createInstructions()` to manually create them. Instructions are written into the same output stream as the new data (just before the new data):

           OutputStream os = consumer.textDeltaChunk(path, window);

  Parameters:
    `is` - a source input stream from where raw delta bytes are read
    `consumer` - an editor that collects diff windows
    `path` - a path of a file for which delta is restored
  Returns:
    true if the method successfully processed the current state and reset to the next one; false in the following cases:
    - the builder is reset to an unknown state
    - can't read raw bytes from `is` due to errors
    - EOF occurred while reading new data from `is` (check if the window `isBuilt()`)
  Throws:
    `SVNException` - if an i/o error occurred while reading from `is`

### save

    public static void save(SVNDiffWindow window,
                            boolean saveHeader,
                            OutputStream os)
                     throws IOException

  Writes the given diff window to the provided output stream as raw delta bytes.

  For the very first diff window `saveHeader` must be true, but if the delta is represented by more than one diff window, call this method for writing the rest windows with `saveHeader` set to false.

  Parameters:
    `window` - a diff window
    `saveHeader` - if true then also writes delta header (the first three characters of which are "SVN"), otherwise starts writing with the window's offsets & lengths
    `os` - a target output stream where raw delta bytes are to be written
  Throws:
    `IOException` - if an i/o error occurred

### createReplacementDiffWindow

    public static SVNDiffWindow createReplacementDiffWindow(long dataLength)

  Creates a diff window intended for replacing the whole contents of a file with new data. It is mainly intended for binary and newly added text files.

  The number of instructions depends on the `dataLength`: one instruction per 100K data chunk.

  Parameters:
    `dataLength` - the length of new data
  Returns:
    a new diff window

### createReplacementDiffWindows

    public static SVNDiffWindow[] createReplacementDiffWindows(long dataLength,
                                                               int maxWindowLength)

  Creates a diff window/windows intended for replacing the whole contents of a file with new data. It is mainly intended for binary and newly added text files.

  The point is that the data length may be too huge, so that one diff window will eat a large amount of memory (on the machine where an svnserve process runs, not JavaSVN) to apply its instructions. It's more safe to devide the contents into a number of smaller windows.

  The number of windows produced depends on `dataLength` and `maxWindowLength`: one diff window (with a single instruction) per `maxWindowLength` data chunk.

  Parameters:
    `dataLength` - the length of new data
    `maxWindowLength` - the maximum length of one diff window
  Returns:
    diff windows

### createInstructions

    public static SVNDiffInstruction[] createInstructions(byte[] bytes)

  Parses, decodes the raw instructions bytes and converts them to diff instruction objects.

  Parameters:
    `bytes` - raw instructions bytes
  Returns:
    diff instruction objects

JavaSVN Home

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