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