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