001/*
002 * Copyright (c) 2006-2014 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the Eclipse Public License v1.0
006 * which accompanies this distribution, and is available at
007 * http://www.eclipse.org/legal/epl-v10.html
008 *
009 * Contributors:
010 *     Florent Guillaume
011 */
012package org.nuxeo.ecm.core.model;
013
014import org.nuxeo.ecm.core.api.Lock;
015
016/**
017 * Manager of locks for a repository.
018 * <p>
019 * The method {@link #close} must be called when done with the lock manager.
020 *
021 * @since 6.0
022 */
023public interface LockManager {
024
025    /**
026     * Gets the lock on a document.
027     * <p>
028     * If the document does not exist, {@code null} is returned.
029     *
030     * @param id the document id
031     * @return the existing lock, or {@code null} when there is no lock
032     */
033    Lock getLock(String id);
034
035    /**
036     * Sets a lock on a document.
037     * <p>
038     * If the document is already locked, returns its existing lock status (there is no re-locking, {@link #removeLock}
039     * must be called first).
040     *
041     * @param id the document id
042     * @param lock the lock to set
043     * @return {@code null} if locking succeeded, or the existing lock if locking failed
044     */
045    Lock setLock(String id, Lock lock);
046
047    /**
048     * Removes the lock from a document.
049     * <p>
050     * The previous lock is returned.
051     * <p>
052     * If {@code owner} is {@code null} then the lock is unconditionally removed.
053     * <p>
054     * If {@code owner} is not {@code null}, it must match the existing lock owner for the lock to be removed. If it
055     * doesn't match, the returned lock will return {@code true} for {@link Lock#getFailed}.
056     *
057     * @param id the document id
058     * @param the owner to check, or {@code null} for no check
059     * @param force {@code true} to just do the remove and not return the previous lock
060     * @return the previous lock (may be {@code null}), with a failed flag if locking failed
061     */
062    Lock removeLock(String id, String owner);
063
064    /**
065     * Checks if a given lock can be removed by the given owner.
066     *
067     * @param oldOwner the existing lock's owner
068     * @param owner the owner (may be {@code null})
069     * @return {@code true} if the lock can be removed
070     */
071    static boolean canLockBeRemoved(String oldOwner, String owner) {
072        return owner == null || owner.equals(oldOwner);
073    }
074
075    /**
076     * Closes the lock manager and releases resources.
077     */
078    void closeLockManager();
079
080    /**
081     * Clears any cache held by the lock manager.
082     */
083    void clearLockManagerCaches();
084
085}