001/*
002 * Copyright (c) 2006-2011 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 *     Nuxeo - initial API and implementation
011 *
012 * $Id$
013 */
014
015package org.nuxeo.ecm.core.api.security;
016
017import java.io.Serializable;
018import java.util.List;
019
020/**
021 * An ACL (Access Control List) is a list of ACEs (Access Control Entry).
022 * <p>
023 * An ACP may contain several ACL identified by a name. This is to let external modules add security rules. There are 2
024 * default ACLs:
025 * <ul>
026 * <li>the <code>local</code> ACL - this is the default type of ACL that may be defined by an user locally to a document
027 * (using a security UI). <br>
028 * This is the only ACL an user can change
029 * <li>the <code>inherited</code> - this is a special ACL generated by merging all document parents ACL. This ACL is
030 * read only (cannot be modified locally on the document since it is inherited.
031 * </ul>
032 * ACLs that are used by external modules cannot be modified by the user through the security UI. These ACLs should be
033 * modified only programmatically by the tool that added them.
034 *
035 * @author <a href="mailto:bs@nuxeo.com">Bogdan Stefanescu</a>
036 */
037public interface ACL extends List<ACE>, Serializable, Cloneable {
038
039    String LOCAL_ACL = "local";
040
041    String INHERITED_ACL = "inherited";
042
043    /**
044     * Gets the ACL name.
045     *
046     * @return the ACL name
047     */
048    String getName();
049
050    /**
051     * Returns the ACEs defined by this list as an array.
052     */
053    ACE[] getACEs();
054
055    /**
056     * Sets the ACEs defined by this ACL.
057     *
058     * @param aces the ACE array
059     */
060    void setACEs(ACE[] aces);
061
062    /**
063     * Block the inheritance.
064     *
065     * @param username the user blocking the inheritance
066     * @return true if the ACL was changed.
067     * @since 7.4
068     */
069    boolean blockInheritance(String username);
070
071    /**
072     * Unblock the inheritance.
073     *
074     * @return true if the ACL was changed.
075     * @since 7.4
076     */
077    boolean unblockInheritance();
078
079    /**
080     * Add an ACE.
081     *
082     * @return true if the ACL was changed.
083     * @since 7.4
084     */
085    boolean add(ACE ace);
086
087    /**
088     * Replace the {@code oldACE} with {@code newACE}, only if the {@code oldACE} exists.
089     * <p>
090     * The {@code newACE} keeps the same index as {@code oldACE}.
091     *
092     * @return true if the ACL was changed.
093     * @since 7.4
094     */
095    boolean replace(ACE oldACE, ACE newACE);
096
097    /**
098     * Remove all ACEs for {@code username}.
099     *
100     * @return true if the ACL was changed.
101     * @since 7.4
102     */
103    boolean removeByUsername(String username);
104
105    /**
106     * Returns a recursive copy of the ACL sharing no mutable substructure with the original.
107     *
108     * @return a copy
109     */
110    Object clone();
111
112}