br.com.objectos.git
Class GitEngine

java.lang.Object
  br.com.objectos.git.GitEngine

public final class GitEngine
extends Object

A state machine providing low-level (plumbing) Git operations.

Instead of using this class directly, users might prefer using StageGitCommand and GitService as they provide means to combine, compose and parallelize git operations.

When using tasks provided by this class, please note that they are not thread-safe and must be run in a single thread. Read GitTask javadoc for more information.

Since:

1

Nested Class Summary

static class

GitEngine.Option A GitEngine configuration option.

Method Summary

static GitEngine.Option	bufferSize(int size) Returns an option that sets the buffer size to the specified value.
GitTask<ImmutableSet<ObjectId>>	copyObjects(Repository source, ImmutableSet<ObjectId> objects, Repository destination) Returns a new task for copying a set of objects from one repository to another.
static GitEngine	create(IoWorker ioWorker, GitEngine.Option... options) Creates and returns a new git engine instance.
static GitEngine.Option	logger(br.com.objectos.logging.Logger logger) Returns an options that sets the logger instance to the specified value.
GitTask<MaterializedEntry>	materializeEntry(Repository repository, Entry entry, Directory target) Returns a new task for materializing a Git tree entry at the specified target directory.
GitTask<Repository>	openRepository(Directory directory) Returns a new task for opening a Git repository located at the specified directory.
GitTask<Blob>	readBlob(Repository repository, ObjectId id) Returns a new task for reading a blob object from a repository.
GitTask<Commit>	readCommit(Repository repository, ObjectId id) Returns a new task for reading a commit object from a repository.
GitTask<Tree>	readTree(Repository repository, ObjectId id) Returns a new task for reading a tree object from a repository.
GitTask<MaybeObjectId>	resolve(Repository repository, RefName ref) Returns a new task for resolving a Git reference.
GitTask<MaybeObjectId>	updateRef(Repository repository, RefName ref, ObjectId newValue) Returns a new task for updating a Git reference.
GitTask<ObjectId>	writeCommit(Repository repository, MutableCommit commit) Returns a new task for writing a commit object (as a loose object) to a repository.
GitTask<ObjectId>	writeTree(Repository repository, MutableTree tree) Returns a new task for recursively writing tree objects to a repository.

Methods inherited from class java.lang.Object

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

Method Detail

bufferSize

public static GitEngine.Option bufferSize(int size)

Returns an option that sets the buffer size to the specified value.

Parameters:

size - the buffer size

Returns:

an option that sets the buffer size to the specified value

Throws:

IllegalArgumentException - if size < 64

create

public static GitEngine create(IoWorker ioWorker,
                               GitEngine.Option... options)

Creates and returns a new git engine instance.

Options are provided by static methods in this class. The available options are:

Options provided by the GitEngine class

Method name	Description	Default value
bufferSize	The size in bytes of the buffers used by this engine	4096
logger	The logger instance the GitEngine will use	NoopLogger.getInstance()

Parameters:

ioWorker - the worker for I/O tasks

options - additional configuration options

Returns:

a new git engine instance

logger

public static GitEngine.Option logger(br.com.objectos.logging.Logger logger)

Returns an options that sets the logger instance to the specified value.

Parameters:

logger - the logger instance

Returns:

an option that sets the logger instance to the specified value

copyObjects

public final GitTask<ImmutableSet<ObjectId>> copyObjects(Repository source,
                                                         ImmutableSet<ObjectId> objects,
                                                         Repository destination)

Returns a new task for copying a set of objects from one repository to another.

The task first determines which of the specified objects are not present in the destination repository. For each of the objects in the resulting subset, the task tries to read it fully (into memory) from the source repository and then it tries to write it to the destination repository. If both the read and write operations succeed it goes to the next object. If, however, either the read or write operation fails, the task stops.

The task, if successful, returns the set of objects that were actually copied, i.e., excluding the ones that were already present in the destination repository before the operation.

Parameters:

source - the source repository containing the objects. Git objects will be read from this repository.

objects - the ids (hash values) of the objects to be copied

destination - the destination repository. Git objects will (possibly) be written to this repository

Returns:

a new task for copying Git objects

Since:

3

materializeEntry

public final GitTask<MaterializedEntry> materializeEntry(Repository repository,
                                                         Entry entry,
                                                         Directory target)

Returns a new task for materializing a Git tree entry at the specified target directory.

If the entry denotes a tree object, the operation will attempt to create a child directory (relative to the specified target directory) having the same name as the entry name. If the directory already exists, the operation will simply return the existing directory (wrapped in a MaterializedEntry instance).

If the entry denotes a blob object, the operation will attempt to read the blob contents from the specified repository. If it succeeds reading the contents, it will write all bytes to a regular file having the same name as entry name and located at the specified target directory. If the file does not exist it will be created, if the file already exists it will be overwritten.

Parameters:

repository - repository to read blob contents from (if necessary)

entry - the entry to be materialized

target - the target directory

Returns:

a new task for materializing a Git tree entry

Since:

3

openRepository

public final GitTask<Repository> openRepository(Directory directory)

Returns a new task for opening a Git repository located at the specified directory.

A Repository instance is required for most Git operations provided by this class. The open repository operation succeeds if the specified directory is an actual Git repository and it fails otherwise. The operation will also fail if an I/O error occurs.

As of the current release the operation will fail if the specified directory is not a bare repository.

Parameters:

directory - the directory where a Git repository is located

Returns:

a new task for opening a repository

Since:

1

readBlob

public final GitTask<Blob> readBlob(Repository repository,
                                    ObjectId id)

Returns a new task for reading a blob object from a repository.

The returned task will fail if an object with the specified hash cannot be found, if an object with the specified hash exists but is not a blob object or if there is a parse error.

Parameters:

repository - the git repository from which to read the commit

id - the unique hash value of the blob to read

Returns:

a new task for reading a blob object

Since:

3

readCommit

public final GitTask<Commit> readCommit(Repository repository,
                                        ObjectId id)

Returns a new task for reading a commit object from a repository.

The returned task will fail if an object with the specified hash cannot be found, if an object with the specified hash exists but is not a commit object or if there is a parse error.

Parameters:

repository - the git repository from which to read the commit

id - the unique hash value of the commit to read

Returns:

a new task for reading a commit object

Since:

2

readTree

public final GitTask<Tree> readTree(Repository repository,
                                    ObjectId id)

Returns a new task for reading a tree object from a repository.

The returned task will fail if an object with the specified hash cannot be found, if an object with the specified hash exists but is not a tree object, if there is a parse error or if an I/O error occurs.

Parameters:

repository - the git repository from which to read the tree

id - the unique hash value of the tree to read

Returns:

a new task for reading a tree object

Since:

2

resolve

public final GitTask<MaybeObjectId> resolve(Repository repository,
                                            RefName ref)

Returns a new task for resolving a Git reference. To resolve a Git reference is to find the object ID associated to it.

Parameters:

repository - the repository for which the reference will be resolved

ref - the Git reference to be resolved

Returns:

a new task for resolving a Git reference

Since:

1

updateRef

public final GitTask<MaybeObjectId> updateRef(Repository repository,
                                              RefName ref,
                                              ObjectId newValue)

Returns a new task for updating a Git reference.

Parameters:

repository - the repository for which the reference will be updated

ref - the Git reference to be updated

newValue - the new value for the reference

Returns:

a new task for updating a Git reference

Since:

3

writeCommit

public final GitTask<ObjectId> writeCommit(Repository repository,
                                           MutableCommit commit)

Returns a new task for writing a commit object (as a loose object) to a repository.

The task will first verify if the specified commit have all of the mandatory properties defined. If not, the task fails. Otherwise it will assemble the Git commit object and will try to write it as a loose object. If the loose object already exists the task assumes it is correct and returns. If the loose object does not exist, the task creates it and the data is written.

As of the current release the operation will create a loose object even if the same commit object exists in a pack file.

Parameters:

repository - the git repository where the commit is to be written

commit - a MutableCommit instance containing all the information to be recorded as a commit object

Returns:

a new task for writing a commit object

Since:

3

writeTree

public final GitTask<ObjectId> writeTree(Repository repository,
                                         MutableTree tree)

Returns a new task for recursively writing tree objects to a repository. The task is recursive in the sense that, if an entry in the specified tree is itself a MutableTree instance, then it will also be written.

As of the current release the operation will create loose objects even if the same object exists in a pack file.

Parameters:

repository - the git repository where the tree is to be written

tree - a MutableTree to be written

Returns:

a new task for writing a tree object

Since:

3