001package de.deepamehta.accesscontrol;
002
003import de.deepamehta.core.Association;
004import de.deepamehta.core.Topic;
005import de.deepamehta.core.service.accesscontrol.Credentials;
006import de.deepamehta.core.service.accesscontrol.Permissions;
007import de.deepamehta.core.service.accesscontrol.SharingMode;
008
009import java.util.Collection;
010
011
012
013public interface AccessControlService {
014
015    // ------------------------------------------------------------------------------------------------------- Constants
016
017    // Admin user account
018    static final String ADMIN_USERNAME = "admin";
019    static final String ADMIN_INITIAL_PASSWORD = System.getProperty("dm4.security.initial_admin_password", "");
020
021    // Administration workspace
022    static final String ADMINISTRATION_WORKSPACE_NAME = "Administration";
023    static final String ADMINISTRATION_WORKSPACE_URI = "dm4.workspaces.administration";
024    static final SharingMode ADMINISTRATION_WORKSPACE_SHARING_MODE = SharingMode.COLLABORATIVE;
025
026    // System workspace
027    static final String SYSTEM_WORKSPACE_NAME = "System";
028    static final String SYSTEM_WORKSPACE_URI = "dm4.workspaces.system";
029    static final SharingMode SYSTEM_WORKSPACE_SHARING_MODE = SharingMode.PUBLIC;
030
031    // Private workspaces
032    static final String DEFAULT_PRIVATE_WORKSPACE_NAME = "Private Workspace";
033
034    // -------------------------------------------------------------------------------------------------- Public Methods
035
036
037
038    // === User Session ===
039
040    /**
041     * Checks weather the credentials in the authorization string match an existing User Account,
042     * and if so, creates an HTTP session. ### FIXDOC
043     *
044     * @param   authHeader  the authorization string containing the credentials. ### FIXDOC
045     *                      Formatted like a "Authorization" HTTP header value. That is, "Basic " appended by the
046     *                      Base64 encoded form of "{username}:{password}".
047     *
048     * @return  ### FIXDOC: The username of the matched User Account (a Topic of type "Username" /
049     *          <code>dm4.accesscontrol.username</code>), or <code>null</code> if there is no matching User Account.
050     */
051    void login();
052
053    /**
054     * Logs the user out. That is invalidating the session associated with the JSESSION ID cookie.
055     *
056     * For a "non-private" DM installation the response is 204 No Content.
057     * For a "private" DM installation the response is 401 Authorization Required. In this case the webclient is
058     * supposed to shutdown the DM GUI then. The webclient of a "private" DM installation must only be visible/usable
059     * when logged in.
060     */
061    void logout();
062
063    // ---
064
065    /**
066     * Returns the username of the logged in user.
067     *
068     * @return  The username, or <code>null</code> if no user is logged in.
069     */
070    String getUsername();
071
072    /**
073     * Returns the "Username" topic of the logged in user.
074     *
075     * @return  The "Username" topic (type <code>dm4.accesscontrol.username</code>),
076     *          or <code>null</code> if no user is logged in.
077     */
078    Topic getUsernameTopic();
079
080    // ---
081
082    /**
083     * Returns the private workspace of the logged in user.
084     * If no user is logged in an exception is thrown.
085     * <p>
086     * Note: a user can have more than one private workspace. The workspace returned
087     * by this method is the one that holds the user's password topic.
088     */
089    Topic getPrivateWorkspace();
090
091
092
093    // === User Accounts ===
094
095    /**
096     * @return  The "Username" topic of the created user account.
097     */
098    Topic createUserAccount(Credentials cred);
099
100    /**
101     * Returns the "Username" topic for the specified username.
102     *
103     * @param   username    a username. Must not be null.
104     *
105     * @return  The "Username" topic (type <code>dm4.accesscontrol.username</code>),
106     *          or <code>null</code> if no such username exists.
107     */
108    Topic getUsernameTopic(String username);
109
110
111
112    // === Workspaces / Memberships ===
113
114    /**
115     * Returns the owner of a workspace.
116     *
117     * @return  The username of the owner, or <code>null</code> if no owner is set.
118     *          ### TODO: should throw an exception instead of returning null
119     */
120    String getWorkspaceOwner(long workspaceId);
121
122    /**
123     * Sets the owner of a workspace.
124     * ### TODO: should take an ID instead a topic.
125     * ### Core service must be extended with a property setter.
126     */
127    void setWorkspaceOwner(Topic workspace, String username);
128
129    // ---
130
131    void createMembership(String username, long workspaceId);
132
133    /**
134     * Checks if a user is a member of the given workspace.
135     *
136     * @param   username        the user.
137     *                          If <code>null</code> is passed, <code>false</code> is returned.
138     *                          If an unknown username is passed an exception is thrown.
139     * @param   workspaceId     the workspace.
140     *
141     * @return  <code>true</code> if the user is a member, <code>false</code> otherwise.
142     */
143    boolean isMember(String username, long workspaceId);
144
145
146
147    // === Permissions ===
148
149    /**
150     * @return  A Permissions object with one entry: <code>dm4.accesscontrol.operation.write</code>.
151     */
152    Permissions getTopicPermissions(long topicId);
153
154    /**
155     * @return  A Permissions object with one entry: <code>dm4.accesscontrol.operation.write</code>.
156     */
157    Permissions getAssociationPermissions(long assocId);
158
159
160
161    // === Object Info ===
162
163    /**
164     * Returns the creator of a topic or an association.
165     *
166     * @return  The username of the creator, or <code>null</code> if no creator is set.
167     */
168    String getCreator(long objectId);
169
170    /**
171     * Returns the modifier of a topic or an association.
172     *
173     * @return  The username of the modifier, or <code>null</code> if no modifier is set.
174     */
175    String getModifier(long objectId);
176
177
178
179    // === Retrieval ===
180
181    Collection<Topic> getTopicsByCreator(String username);
182
183    Collection<Topic> getTopicsByOwner(String username);
184
185    Collection<Association> getAssociationsByCreator(String username);
186
187    Collection<Association> getAssociationsByOwner(String username);
188}