JavaSVN Home

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

java.lang.Object
  extended byorg.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:

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.