NoteMap.java

/*
 * Copyright (C) 2010, Google Inc. and others
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Distribution License v. 1.0 which is available at
 * https://www.eclipse.org/org/documents/edl-v10.php.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 */

package org.eclipse.jgit.notes;

import java.io.IOException;
import java.util.Iterator;

import org.eclipse.jgit.errors.CorruptObjectException;
import org.eclipse.jgit.errors.IncorrectObjectTypeException;
import org.eclipse.jgit.errors.LargeObjectException;
import org.eclipse.jgit.errors.MissingObjectException;
import org.eclipse.jgit.lib.AbbreviatedObjectId;
import org.eclipse.jgit.lib.AnyObjectId;
import org.eclipse.jgit.lib.Constants;
import org.eclipse.jgit.lib.MutableObjectId;
import org.eclipse.jgit.lib.ObjectId;
import org.eclipse.jgit.lib.ObjectInserter;
import org.eclipse.jgit.lib.ObjectReader;
import org.eclipse.jgit.revwalk.RevCommit;
import org.eclipse.jgit.revwalk.RevTree;

/**
 * Index of notes from a note branch.
 *
 * This class is not thread-safe, and relies on an
 * {@link org.eclipse.jgit.lib.ObjectReader} that it borrows/shares with the
 * caller. The reader can be used during any call, and is not released by this
 * class. The caller should arrange for releasing the shared
 * {@code ObjectReader} at the proper times.
 */
public class NoteMap implements Iterable<Note> {
    /**
     * Construct a new empty note map.
     *
     * @return an empty note map.
     */
    public static NoteMap newEmptyMap() {
        NoteMap r = new NoteMap(null /* no reader */);
        r.root = new LeafBucket(0);
        return r;
    }

    /**
     * Shorten the note ref name by trimming off the
     * {@link org.eclipse.jgit.lib.Constants#R_NOTES} prefix if it exists.
     *
     * @param noteRefName
     *            a {@link java.lang.String} object.
     * @return a more user friendly note name
     */
    public static String shortenRefName(String noteRefName) {
        if (noteRefName.startsWith(Constants.R_NOTES))
            return noteRefName.substring(Constants.R_NOTES.length());
        return noteRefName;
    }

    /**
     * Load a collection of notes from a branch.
     *
     * @param reader
     *            reader to scan the note branch with. This reader may be
     *            retained by the NoteMap for the life of the map in order to
     *            support lazy loading of entries.
     * @param commit
     *            the revision of the note branch to read.
     * @return the note map read from the commit.
     * @throws java.io.IOException
     *             the repository cannot be accessed through the reader.
     * @throws org.eclipse.jgit.errors.CorruptObjectException
     *             a tree object is corrupt and cannot be read.
     * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
     *             a tree object wasn't actually a tree.
     * @throws org.eclipse.jgit.errors.MissingObjectException
     *             a reference tree object doesn't exist.
     */
    public static NoteMap read(ObjectReader reader, RevCommit commit)
            throws MissingObjectException, IncorrectObjectTypeException,
            CorruptObjectException, IOException {
        return read(reader, commit.getTree());
    }

    /**
     * Load a collection of notes from a tree.
     *
     * @param reader
     *            reader to scan the note branch with. This reader may be
     *            retained by the NoteMap for the life of the map in order to
     *            support lazy loading of entries.
     * @param tree
     *            the note tree to read.
     * @return the note map read from the tree.
     * @throws java.io.IOException
     *             the repository cannot be accessed through the reader.
     * @throws org.eclipse.jgit.errors.CorruptObjectException
     *             a tree object is corrupt and cannot be read.
     * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
     *             a tree object wasn't actually a tree.
     * @throws org.eclipse.jgit.errors.MissingObjectException
     *             a reference tree object doesn't exist.
     */
    public static NoteMap read(ObjectReader reader, RevTree tree)
            throws MissingObjectException, IncorrectObjectTypeException,
            CorruptObjectException, IOException {
        return readTree(reader, tree);
    }

    /**
     * Load a collection of notes from a tree.
     *
     * @param reader
     *            reader to scan the note branch with. This reader may be
     *            retained by the NoteMap for the life of the map in order to
     *            support lazy loading of entries.
     * @param treeId
     *            the note tree to read.
     * @return the note map read from the tree.
     * @throws java.io.IOException
     *             the repository cannot be accessed through the reader.
     * @throws org.eclipse.jgit.errors.CorruptObjectException
     *             a tree object is corrupt and cannot be read.
     * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
     *             a tree object wasn't actually a tree.
     * @throws org.eclipse.jgit.errors.MissingObjectException
     *             a reference tree object doesn't exist.
     */
    public static NoteMap readTree(ObjectReader reader, ObjectId treeId)
            throws MissingObjectException, IncorrectObjectTypeException,
            CorruptObjectException, IOException {
        NoteMap map = new NoteMap(reader);
        map.load(treeId);
        return map;
    }

    /**
     * Construct a new note map from an existing note bucket.
     *
     * @param root
     *            the root bucket of this note map
     * @param reader
     *            reader to scan the note branch with. This reader may be
     *            retained by the NoteMap for the life of the map in order to
     *            support lazy loading of entries.
     * @return the note map built from the note bucket
     */
    static NoteMap newMap(InMemoryNoteBucket root, ObjectReader reader) {
        NoteMap map = new NoteMap(reader);
        map.root = root;
        return map;
    }

    /** Borrowed reader to access the repository. */
    private final ObjectReader reader;

    /** All of the notes that have been loaded. */
    private InMemoryNoteBucket root;

    private NoteMap(ObjectReader reader) {
        this.reader = reader;
    }

    /** {@inheritDoc} */
    @Override
    public Iterator<Note> iterator() {
        try {
            return root.iterator(new MutableObjectId(), reader);
        } catch (IOException e) {
            throw new RuntimeException(e);
        }
    }

    /**
     * Lookup a note for a specific ObjectId.
     *
     * @param id
     *            the object to look for.
     * @return the note's blob ObjectId, or null if no note exists.
     * @throws java.io.IOException
     *             a portion of the note space is not accessible.
     */
    public ObjectId get(AnyObjectId id) throws IOException {
        Note n = root.getNote(id, reader);
        return n == null ? null : n.getData();
    }

    /**
     * Lookup a note for a specific ObjectId.
     *
     * @param id
     *            the object to look for.
     * @return the note for the given object id, or null if no note exists.
     * @throws java.io.IOException
     *             a portion of the note space is not accessible.
     */
    public Note getNote(AnyObjectId id) throws IOException {
        return root.getNote(id, reader);
    }

    /**
     * Determine if a note exists for the specified ObjectId.
     *
     * @param id
     *            the object to look for.
     * @return true if a note exists; false if there is no note.
     * @throws java.io.IOException
     *             a portion of the note space is not accessible.
     */
    public boolean contains(AnyObjectId id) throws IOException {
        return get(id) != null;
    }

    /**
     * Open and return the content of an object's note.
     *
     * This method assumes the note is fairly small and can be accessed
     * efficiently. Larger notes should be accessed by streaming:
     *
     * <pre>
     * ObjectId dataId = thisMap.get(id);
     * if (dataId != null)
     *  reader.open(dataId).openStream();
     * </pre>
     *
     * @param id
     *            object to lookup the note of.
     * @param sizeLimit
     *            maximum number of bytes to return. If the note data size is
     *            larger than this limit, LargeObjectException will be thrown.
     * @return if a note is defined for {@code id}, the note content. If no note
     *         is defined, null.
     * @throws org.eclipse.jgit.errors.LargeObjectException
     *             the note data is larger than {@code sizeLimit}.
     * @throws org.eclipse.jgit.errors.MissingObjectException
     *             the note's blob does not exist in the repository.
     * @throws java.io.IOException
     *             the note's blob cannot be read from the repository
     */
    public byte[] getCachedBytes(AnyObjectId id, int sizeLimit)
            throws LargeObjectException, MissingObjectException, IOException {
        ObjectId dataId = get(id);
        if (dataId != null) {
            return reader.open(dataId).getCachedBytes(sizeLimit);
        }
        return null;
    }

    /**
     * Attach (or remove) a note on an object.
     *
     * If no note exists, a new note is stored. If a note already exists for the
     * given object, it is replaced (or removed).
     *
     * This method only updates the map in memory.
     *
     * If the caller wants to attach a UTF-8 encoded string message to an
     * object, {@link #set(AnyObjectId, String, ObjectInserter)} is a convenient
     * way to encode and update a note in one step.
     *
     * @param noteOn
     *            the object to attach the note to. This same ObjectId can later
     *            be used as an argument to {@link #get(AnyObjectId)} or
     *            {@link #getCachedBytes(AnyObjectId, int)} to read back the
     *            {@code noteData}.
     * @param noteData
     *            data to associate with the note. This must be the ObjectId of
     *            a blob that already exists in the repository. If null the note
     *            will be deleted, if present.
     * @throws java.io.IOException
     *             a portion of the note space is not accessible.
     */
    public void set(AnyObjectId noteOn, ObjectId noteData) throws IOException {
        InMemoryNoteBucket newRoot = root.set(noteOn, noteData, reader);
        if (newRoot == null) {
            newRoot = new LeafBucket(0);
            newRoot.nonNotes = root.nonNotes;
        }
        root = newRoot;
    }

    /**
     * Attach a note to an object.
     *
     * If no note exists, a new note is stored. If a note already exists for the
     * given object, it is replaced (or removed).
     *
     * @param noteOn
     *            the object to attach the note to. This same ObjectId can later
     *            be used as an argument to {@link #get(AnyObjectId)} or
     *            {@link #getCachedBytes(AnyObjectId, int)} to read back the
     *            {@code noteData}.
     * @param noteData
     *            text to store in the note. The text will be UTF-8 encoded when
     *            stored in the repository. If null the note will be deleted, if
     *            the empty string a note with the empty string will be stored.
     * @param ins
     *            inserter to write the encoded {@code noteData} out as a blob.
     *            The caller must ensure the inserter is flushed before the
     *            updated note map is made available for reading.
     * @throws java.io.IOException
     *             the note data could not be stored in the repository.
     */
    public void set(AnyObjectId noteOn, String noteData, ObjectInserter ins)
            throws IOException {
        ObjectId dataId;
        if (noteData != null) {
            byte[] dataUTF8 = Constants.encode(noteData);
            dataId = ins.insert(Constants.OBJ_BLOB, dataUTF8);
        } else {
            dataId = null;
        }
        set(noteOn, dataId);
    }

    /**
     * Remove a note from an object.
     *
     * If no note exists, no action is performed.
     *
     * This method only updates the map in memory.
     *
     * @param noteOn
     *            the object to remove the note from.
     * @throws java.io.IOException
     *             a portion of the note space is not accessible.
     */
    public void remove(AnyObjectId noteOn) throws IOException {
        set(noteOn, null);
    }

    /**
     * Write this note map as a tree.
     *
     * @param inserter
     *            inserter to use when writing trees to the object database.
     *            Caller is responsible for flushing the inserter before trying
     *            to read the objects, or exposing them through a reference.
     * @return the top level tree.
     * @throws java.io.IOException
     *             a tree could not be written.
     */
    public ObjectId writeTree(ObjectInserter inserter) throws IOException {
        return root.writeTree(inserter);
    }

    /** @return the root note bucket */
    InMemoryNoteBucket getRoot() {
        return root;
    }

    private void load(ObjectId rootTree) throws MissingObjectException,
            IncorrectObjectTypeException, CorruptObjectException, IOException {
        AbbreviatedObjectId none = AbbreviatedObjectId.fromString(""); //$NON-NLS-1$
        root = NoteParser.parse(none, rootTree, reader);
    }
}