code.grnet.gr Git - pithos/blob - src/gr/ebs/gss/server/ejb/ExternalAPIRemote.java

   1 /*
   2  * Copyright 2007, 2008, 2009 Electronic Business Systems Ltd.
   3  *
   4  * This file is part of GSS.
   5  *
   6  * GSS is free software: you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation, either version 3 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * GSS is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with GSS.  If not, see <http://www.gnu.org/licenses/>.
  18  */
  19 package gr.ebs.gss.server.ejb;
  20
  21 import gr.ebs.gss.client.exceptions.DuplicateNameException;
  22 import gr.ebs.gss.client.exceptions.GSSIOException;
  23 import gr.ebs.gss.client.exceptions.InsufficientPermissionsException;
  24 import gr.ebs.gss.client.exceptions.ObjectNotFoundException;
  25 import gr.ebs.gss.client.exceptions.QuotaExceededException;
  26 import gr.ebs.gss.server.domain.User;
  27 import gr.ebs.gss.server.domain.dto.FileHeaderDTO;
  28 import gr.ebs.gss.server.domain.dto.FolderDTO;
  29 import gr.ebs.gss.server.domain.dto.GroupDTO;
  30 import gr.ebs.gss.server.domain.dto.PermissionDTO;
  31 import gr.ebs.gss.server.domain.dto.UserDTO;
  32
  33 import java.io.InputStream;
  34 import java.util.Date;
  35 import java.util.List;
  36 import java.util.Set;
  37
  38 import javax.ejb.Remote;
  39
  40 /**
  41  * The External API for GSS clients.
  42  *
  43  * @author chstath
  44  */
  45 @Remote
  46 public interface ExternalAPIRemote {
  47
  48         /**
  49          * Retrieves the root folder for the specified user. The caller must ensure
  50          * that the userId exists.
  51          *
  52          * @param userId
  53          * @return Folder
  54          * @throws ObjectNotFoundException if no Folder or user was found
  55          */
  56         public FolderDTO getRootFolder(Long userId) throws ObjectNotFoundException;
  57
  58         /**
  59          * Retrieve the folder with the specified ID.
  60          *
  61          * @param userId the ID of the current user
  62          * @param folderId the ID of the folder to retrieve
  63          * @return the folder found
  64          * @throws ObjectNotFoundException if the folder or the user was not found
  65          * @throws InsufficientPermissionsException if ther user does not have read permissions for folder
  66          */
  67         public FolderDTO getFolder(Long userId, Long folderId) throws ObjectNotFoundException, InsufficientPermissionsException;
  68
  69         /**
  70          * Returns the user with the specified ID.
  71          *
  72          * @param userId The ID of the User to be found
  73          * @return The User object
  74          * @throws ObjectNotFoundException if the user cannot be found
  75          */
  76         public User getUser(Long userId) throws ObjectNotFoundException;
  77
  78         /**
  79          * Returns the user with the specified ID.
  80          *
  81          * @param userId The ID of the User to be found
  82          * @return The User object
  83          * @throws ObjectNotFoundException if the user cannot be found
  84          */
  85         public UserDTO getUserDTO(Long userId) throws ObjectNotFoundException;
  86
  87         /**
  88          * Returns the group with the specified ID.
  89          *
  90          * @param groupId The ID of the Group to be found
  91          * @return The Group object
  92          * @throws ObjectNotFoundException if the group cannot be found
  93          */
  94         public GroupDTO getGroup(Long groupId) throws ObjectNotFoundException;
  95
  96         /**
  97          * Retrieve the list of groups for a particular user.
  98          *
  99          * @param userId the ID of the User
 100          * @return a List of Groups that belong to the specified User
 101          * @throws ObjectNotFoundException if the user was not found
 102          */
 103         public List<GroupDTO> getGroups(Long userId) throws ObjectNotFoundException;
 104
 105         /**
 106          * Returns a list of files contained in the folder specified by its id.
 107          *
 108          * @param userId the ID of the User
 109          * @param folderId the ID of the folder containing the files
 110          * @param ignoreDeleted
 111          * @return the list of file header objects
 112          * @throws ObjectNotFoundException if the user or the folder cannot be found
 113          * @throws InsufficientPermissionsException
 114          */
 115         public List<FileHeaderDTO> getFiles(Long userId, Long folderId, boolean ignoreDeleted) throws ObjectNotFoundException, InsufficientPermissionsException;
 116
 117         /**
 118          * Returns a list of users for the specified group
 119          *
 120          * @param userId the ID of the User
 121          * @param groupId the ID of the requested group
 122          * @return List<UserDTO>
 123          * @throws ObjectNotFoundException if the user or group was not found, with
 124          *             the exception message mentioning the precise problem
 125          */
 126         public List<UserDTO> getUsers(Long userId, Long groupId) throws ObjectNotFoundException;
 127
 128         /**
 129          * Returns a list of users for the specified username
 130          *
 131          * @param username the username of the User
 132          * @return List<UserDTO>
 133          */
 134         public List<UserDTO> getUsersByUserNameLike(String username);
 135
 136         /**
 137          * Creates a new folder with the specified owner, parent folder and name.
 138          * New folder has the same permissions as its parent
 139          *
 140          * @param userId
 141          * @param parentId
 142          * @param name
 143          * @return the new folder
 144          * @throws DuplicateNameException if the specified name already exists in
 145          *             the parent folder, as either a folder or file
 146          * @throws ObjectNotFoundException if the user or parent folder was not
 147          *             found, with the exception message mentioning the precise
 148          *             problem
 149          * @throws InsufficientPermissionsException
 150          */
 151         public FolderDTO createFolder(Long userId, Long parentId, String name) throws DuplicateNameException, ObjectNotFoundException, InsufficientPermissionsException;
 152
 153         /**
 154          * Deletes the specified folder if the specified user has the appropriate
 155          * permission
 156          *
 157          * @param userId
 158          * @param folderId
 159          * @throws InsufficientPermissionsException if the user does not have the
 160          *             appropriate privileges
 161          * @throws ObjectNotFoundException if the user or folder was not found, with
 162          *             the exception message mentioning the precise problem
 163          */
 164         public void deleteFolder(Long userId, Long folderId) throws InsufficientPermissionsException, ObjectNotFoundException;
 165
 166         /**
 167          * Retrieve the subfolders of the specified folder.
 168          *
 169          * @param userId the ID of the current user
 170          * @param folderId the ID of the folder to retrieve
 171          * @return the list of subfolders found
 172          * @throws ObjectNotFoundException if the folder or user was not found
 173          * @throws InsufficientPermissionsException
 174          */
 175         public List<FolderDTO> getSubfolders(Long userId, Long folderId) throws ObjectNotFoundException, InsufficientPermissionsException;
 176
 177
 178         /**
 179          * Retrieve the subfolders of the specified folder that are shared to others.
 180          *
 181          * @param userId the ID of the current user
 182          * @param folderId the ID of the folder to retrieve
 183          * @return the list of subfolders found
 184          * @throws ObjectNotFoundException if the folder or user was not found
 185          */
 186         public List<FolderDTO> getSharedSubfolders(Long userId, Long folderId) throws ObjectNotFoundException;
 187
 188         /**
 189          * Modifies the specified folder if the specified user has the appropriate
 190          * permission.
 191          *
 192          * @param userId the ID of the current user
 193          * @param folderId the ID of the folder to retrieve
 194          * @param folderName
 195          * @param permissions
 196          * @return the updated folder
 197          * @throws InsufficientPermissionsException if the user does not have the
 198          *             appropriate privileges
 199          * @throws ObjectNotFoundException if the user or folder was not found, with
 200          *             the exception message mentioning the precise problem
 201          * @throws DuplicateNameException if the specified name already exists in
 202          *             the parent folder, as either a folder or file
 203          */
 204         public FolderDTO updateFolder(Long userId, Long folderId, String folderName,
 205                                 Set<PermissionDTO> permissions)
 206                         throws InsufficientPermissionsException, ObjectNotFoundException,
 207                         DuplicateNameException;
 208
 209         /**
 210          * Adds a user to the specified group
 211          *
 212          * @param userId the ID of the current user
 213          * @param groupId the id of the new group
 214          * @param userToAddId the id of the user to add
 215          * @throws DuplicateNameException if the user already exists in group
 216          * @throws ObjectNotFoundException if the user or group was not found, with
 217          *             the exception message mentioning the precise problem
 218          * @throws InsufficientPermissionsException
 219          */
 220         public void addUserToGroup(Long userId, Long groupId, Long userToAddId) throws ObjectNotFoundException, DuplicateNameException, InsufficientPermissionsException;
 221
 222         /**
 223          * Creates a new group with the specified owner and name.
 224          *
 225          * @param userId the ID of the current user
 226          * @param name the name of the new group
 227          * @throws DuplicateNameException if the new group name already exists
 228          * @throws ObjectNotFoundException if the user or group was not found, with
 229          *             the exception message mentioning the precise problem
 230          */
 231         public void createGroup(Long userId, String name) throws ObjectNotFoundException, DuplicateNameException;
 232
 233         /**
 234          * Deletes the specified group in the specified user's namespace.
 235          *
 236          * @param userId the ID of the current user
 237          * @param groupId the ID of the group to delete
 238          * @throws ObjectNotFoundException if the user or group was not found, with
 239          *             the exception message mentioning the precise problem
 240          * @throws InsufficientPermissionsException
 241          */
 242         public void deleteGroup(Long userId, Long groupId) throws ObjectNotFoundException, InsufficientPermissionsException;
 243
 244         /**
 245          * Creates a new file with the specified owner, parent folder and name. The
 246          * new file has the same permissions as its parent folder. The file contents
 247          * are read from the input stream to a new File object.
 248          *
 249          * @param userId the ID of the current user
 250          * @param folderId the ID of the parent folder
 251          * @param name the name of the new file
 252          * @param mimeType the MIME type of the file
 253          * @param stream the input stream with the file contents
 254          * @return The FileHeaderDTO created
 255          * @throws DuplicateNameException if the specified name already exists in
 256          *             the parent folder, as either a folder or file
 257          * @throws ObjectNotFoundException if the user or parent folder was not
 258          *             found, with the exception message mentioning the precise
 259          *             problem
 260          * @throws GSSIOException if there was an error while storing the file contents
 261          * @throws InsufficientPermissionsException
 262          */
 263         public FileHeaderDTO createFile(Long userId, Long folderId, String name, String mimeType, InputStream stream) throws DuplicateNameException, ObjectNotFoundException, GSSIOException, InsufficientPermissionsException, QuotaExceededException;
 264
 265         /**
 266          * Deletes the specified file in the specified user's namespace.
 267          *
 268          * @param userId the ID of the current user
 269          * @param fileId the ID of the file to delete
 270          * @throws ObjectNotFoundException if the user or file was not found, with
 271          *             the exception message mentioning the precise problem
 272          * @throws InsufficientPermissionsException if the user does not have the
 273          *             appropriate privileges
 274          */
 275         public void deleteFile(Long userId, Long fileId) throws ObjectNotFoundException, InsufficientPermissionsException;
 276
 277         /**
 278          * Creates a new tag for the specified user and file.
 279          *
 280          * @param userId the creator of the tag
 281          * @param fileHeaderId the file that is tagged
 282          * @param tag the tag
 283          * @throws ObjectNotFoundException if the user or the file was not found
 284          */
 285         public void createTag(Long userId, Long fileHeaderId, String tag) throws ObjectNotFoundException;
 286
 287         /**
 288          * Returns all tags defined by the specified user
 289          *
 290          * @param userId
 291          * @return Set<String>
 292          * @throws ObjectNotFoundException if the user was null
 293          */
 294         public Set<String> getUserTags(final Long userId) throws ObjectNotFoundException;
 295
 296         /**
 297          * Updates the attributes of the specified file.
 298          *
 299          * @param userId
 300          * @param fileId
 301          * @param name
 302          * @param tagSet a String that contains tags separated by comma
 303          * @param modificationDate the modification date
 304          * @param versioned the new value of the versioned flag
 305          * @param readForAll
 306          * @param permissions
 307          * @throws DuplicateNameException
 308          * @throws ObjectNotFoundException
 309          * @throws InsufficientPermissionsException
 310          */
 311         public void updateFile(Long userId, Long fileId, String name, String tagSet,
 312                         Date modificationDate, Boolean versioned, Boolean readForAll,
 313                         Set<PermissionDTO> permissions)
 314                         throws DuplicateNameException, ObjectNotFoundException, InsufficientPermissionsException;
 315
 316         /**
 317          * Retrieve the contents of the current body for the file
 318          * with the specified FileHeader ID. The file contents
 319          * are provided as an InputStream from which the caller can
 320          * retrieve the raw bytes.
 321          *
 322          * @param userId the ID of the current user
 323          * @param fileId the ID of the file to retrieve
 324          * @return an InputStream from the current file body contents
 325          * @throws ObjectNotFoundException if the file or the user was not found
 326          * @throws InsufficientPermissionsException  if the user does not have the
 327          *             appropriate privileges
 328          */
 329         public InputStream getFileContents(Long userId, Long fileId) throws ObjectNotFoundException, InsufficientPermissionsException;
 330
 331         /**
 332          * Retrieve the file with the specified ID.
 333          *
 334          * @param userId the ID of the current user
 335          * @param fileId the ID of the file to retrieve
 336          * @return the file found
 337          * @throws ObjectNotFoundException if the file or the user was not found, with
 338          *                      the exception message mentioning the precise problem
 339          * @throws InsufficientPermissionsException
 340          */
 341         public FileHeaderDTO getFile(Long userId, Long fileId) throws ObjectNotFoundException, InsufficientPermissionsException;
 342
 343         /**
 344          * Get the resource (file or folder) at the specified path in
 345          * the specified user's namespace. The returned object will be of type
 346          * FileHeaderDTO or FolderDTO.<p><strong>Note:</strong> this method does not
 347          * receive the current user as a parameter, therefore it is unable to perform
 348          * the necessary permission checks and should <strong>NOT</strong> be directly
 349          * exposed to remote clients. It is the caller's responsibility to verify that
 350          * the calling user has the required privileges for performing any subsequent
 351          * action on the resource through one of the other ExternalAPI methods.
 352          *
 353          * @param ownerId the ID of the user owning the namespace
 354          * @param path the absolute path in the user's namespace
 355          * @param ignoreDeleted if true, resources that have been moved to the trash
 356          *                      will be ignored
 357          * @throws ObjectNotFoundException if the user or resource was not found, with
 358          *                      the exception message mentioning the precise problem
 359          * @return the resource found
 360          */
 361         public Object getResourceAtPath(Long ownerId, String path, boolean ignoreDeleted)
 362                         throws ObjectNotFoundException;
 363
 364         /**
 365          * Copy the provided file to the specified destination.
 366          *
 367          * @param userId the ID of the current user
 368          * @param fileId the IF of the provided file
 369          * @param dest the path to the destination folder
 370          * @throws ObjectNotFoundException if the user, file or destination was not
 371          *                      found, with     the exception message mentioning the precise problem
 372          * @throws GSSIOException if there was an error while accessing the file contents
 373          * @throws DuplicateNameException if the specified name already exists in
 374          *          the destination folder, as either a folder or file
 375          * @throws InsufficientPermissionsException
 376          */
 377         public void copyFile(Long userId, Long fileId, String dest) throws ObjectNotFoundException, DuplicateNameException, GSSIOException, InsufficientPermissionsException, QuotaExceededException;
 378
 379         /**
 380          * Copy the provided file to the specified destination.
 381          *
 382          * @param userId the ID of the current user
 383          * @param fileId the IF of the provided file
 384          * @param destId the ID of the destination folder
 385          * @param destName the name of the new file
 386          * @throws ObjectNotFoundException if the user, file or destination was not
 387          *                      found, with     the exception message mentioning the precise problem
 388          * @throws GSSIOException if there was an error while accessing the file contents
 389          * @throws DuplicateNameException if the specified name already exists in
 390          *          the destination folder, as either a folder or file
 391          * @throws InsufficientPermissionsException
 392          */
 393         public void copyFile(Long userId, Long fileId, Long destId, String destName) throws ObjectNotFoundException, DuplicateNameException, GSSIOException, InsufficientPermissionsException, QuotaExceededException;
 394
 395         /**
 396          * Copy the provided folder to the specified destination.
 397          *
 398          * @param userId the ID of the current user
 399          * @param folderId the IF of the provided folder
 400          * @param dest the path to the destination folder
 401          * @throws ObjectNotFoundException if the user, folder or destination was not
 402          *                      found, with     the exception message mentioning the precise problem
 403          * @throws DuplicateNameException if the specified name already exists in
 404          *          the destination folder, as either a folder or file
 405          * @throws InsufficientPermissionsException InsufficientPermissionsException if the user does not have the
 406          *          appropriate privileges
 407          */
 408         public void copyFolder(Long userId, Long folderId, String dest) throws ObjectNotFoundException, DuplicateNameException, InsufficientPermissionsException, QuotaExceededException;
 409
 410         /**
 411          * Copy the provided folder to the specified destination.
 412          *
 413          * @param userId the ID of the current user
 414          * @param folderId the IF of the provided folder
 415          * @param destId the ID of the destination folder
 416          * @param destName the name of the new folder
 417          * @throws ObjectNotFoundException if the user, folder or destination was not
 418          *                      found, with     the exception message mentioning the precise problem
 419          * @throws DuplicateNameException if the specified name already exists in
 420          *          the destination folder, as either a folder or file
 421          * @throws InsufficientPermissionsException InsufficientPermissionsException if the user does not have the
 422          *          appropriate privileges
 423          */
 424         public void copyFolder(Long userId, Long folderId, Long destId, String destName) throws ObjectNotFoundException, DuplicateNameException, InsufficientPermissionsException, QuotaExceededException;
 425
 426         /**
 427          * Copy the provided folder and all its subfolders and files to the specified destination.
 428          *
 429          * @param userId the ID of the current user
 430          * @param folderId the IF of the provided folder
 431          * @param destId the ID of the destination folder
 432          * @param destName the name of the new folder
 433          * @throws ObjectNotFoundException if the user, folder or destination was not
 434          *                      found, with     the exception message mentioning the precise problem
 435          * @throws DuplicateNameException if the specified name already exists in
 436          *          the destination folder, as either a folder or file
 437          * @throws InsufficientPermissionsException InsufficientPermissionsException if the user does not have the
 438          *          appropriate privileges
 439          * @throws GSSIOException
 440          */
 441         public void copyFolderStructure(Long userId, Long folderId, Long destId, String destName) throws ObjectNotFoundException, DuplicateNameException, InsufficientPermissionsException,GSSIOException, QuotaExceededException;
 442
 443         /**
 444          * Marks  the specified file as deleted in the specified user's namespace.
 445          *
 446          * @param userId the ID of the current user
 447          * @param fileId the ID of the file to delete
 448          * @throws ObjectNotFoundException if the user or file was not found, with
 449          *             the exception message mentioning the precise problem
 450          * @throws InsufficientPermissionsException if the user does not have the
 451          *             appropriate privileges
 452          */
 453         public void moveFileToTrash(Long userId, Long fileId) throws ObjectNotFoundException, InsufficientPermissionsException;
 454
 455         /**
 456          * Marks  the specified deleted file as undeleted in the specified user's namespace.
 457          *
 458          * @param userId the ID of the current user
 459          * @param fileId the ID of the file to undelete
 460          * @throws ObjectNotFoundException if the user or file was not found, with
 461          *             the exception message mentioning the precise problem
 462          * @throws InsufficientPermissionsException if the user does not have the
 463          *             appropriate privileges
 464          */
 465         public void removeFileFromTrash(Long userId, Long fileId) throws ObjectNotFoundException, InsufficientPermissionsException;
 466
 467         /**
 468          * Marks  the specified folder as deleted in the specified user's namespace.
 469          *
 470          * @param userId the ID of the current user
 471          * @param folderId the ID of the folder to delete
 472          * @throws ObjectNotFoundException if the user or file was not found, with
 473          *             the exception message mentioning the precise problem
 474          * @throws InsufficientPermissionsException if the user does not have the
 475          *             appropriate privileges
 476          */
 477         public void moveFolderToTrash(Long userId, Long folderId) throws ObjectNotFoundException, InsufficientPermissionsException;
 478
 479         /**
 480          * Marks  the specified deleted folder as undeleted in the specified user's namespace.
 481          *
 482          * @param userId the ID of the current user
 483          * @param folderId the ID of the folder to undelete
 484          * @throws ObjectNotFoundException if the user or file was not found, with
 485          *             the exception message mentioning the precise problem
 486          * @throws InsufficientPermissionsException if the user does not have the
 487          *             appropriate privileges
 488          */
 489         public void removeFolderFromTrash(Long userId, Long folderId) throws ObjectNotFoundException, InsufficientPermissionsException;
 490
 491         /**
 492          * Move the provided folder and all its subfolders and files to the specified destination.
 493          *
 494          * @param userId the ID of the current user
 495          * @param folderId the IF of the provided folder
 496          * @param destId the ID of the destination folder
 497          * @param destName the name of the new folder
 498          * @throws ObjectNotFoundException if the user, folder or destination was not
 499          *                      found, with     the exception message mentioning the precise problem
 500          * @throws DuplicateNameException if the specified name already exists in
 501          *          the destination folder, as either a folder or file
 502          * @throws InsufficientPermissionsException if the user does not have the
 503          *          appropriate privileges
 504          * @throws GSSIOException
 505          */
 506         public void moveFolder(Long userId, Long folderId, Long destId, String destName) throws ObjectNotFoundException, DuplicateNameException, InsufficientPermissionsException, GSSIOException, QuotaExceededException;
 507
 508         /**
 509          * move the provided file to the specified destination.
 510          *
 511          * @param userId the ID of the current user
 512          * @param fileId the IF of the provided file
 513          * @param destId the ID of the destination folder
 514          * @param destName the name of the new file
 515          * @throws InsufficientPermissionsException
 516          * @throws ObjectNotFoundException if the user, file or destination was not
 517          *                      found, with     the exception message mentioning the precise problem
 518          * @throws GSSIOException if there was an error while accessing the file contents
 519          * @throws DuplicateNameException if the specified name already exists in
 520          *          the destination folder, as either a folder or file
 521          */
 522         public void moveFile(Long userId, Long fileId, Long destId, String destName) throws InsufficientPermissionsException, ObjectNotFoundException, DuplicateNameException, GSSIOException, QuotaExceededException;
 523
 524         /**
 525          * Returns a list of All deleted files of a user.
 526          *
 527          * @param userId the ID of the User
 528          *       * @return the list of deleted file header objects
 529          * @throws ObjectNotFoundException if the user cannot be found
 530          */
 531         public List<FileHeaderDTO> getDeletedFiles(Long userId) throws ObjectNotFoundException;
 532
 533         /**
 534          * Returns a list of All deleted root folders of a user.
 535          *
 536          * @param userId the ID of the User
 537          *       * @return the list of deleted file header objects
 538          * @throws ObjectNotFoundException if the user cannot be found
 539          */
 540         public List<FolderDTO> getDeletedRootFolders(Long userId) throws ObjectNotFoundException;
 541
 542         /**
 543          * Empty Trash by deleting all marked as deleted files and folders
 544          * @param userId
 545          * @throws ObjectNotFoundException if something goes wrong in the delete process
 546          * @throws InsufficientPermissionsException  if something goes wrong in the delete process
 547          */
 548         public void emptyTrash(Long userId) throws ObjectNotFoundException, InsufficientPermissionsException;
 549
 550         /**
 551          * Restores All Trashed Items by undeleting all marked as deleted files and folders
 552          * @param userId
 553          * @throws ObjectNotFoundException if something goes wrong in the delete process
 554          * @throws InsufficientPermissionsException if the user does not have the
 555          *          appropriate privileges
 556          */
 557         public void restoreTrash(Long userId) throws ObjectNotFoundException, InsufficientPermissionsException;
 558
 559         /**
 560          * Search the system for a user with the specified username.
 561          * If no such user is found, the method returns null.
 562          *
 563          * @param username the username to search for
 564          * @return the User object with the specified username
 565          */
 566         public User findUser(String username);
 567
 568         /**
 569          * Create a new user with the specified name, username and e-mail address.
 570          *
 571          * @param username the username of the new user
 572          * @param name the full name of the new user
 573          * @param mail the e-mail of the new user
 574          * @param persistentId the persistentId of the new user
 575          * @return the newly-created User object
 576          * @throws DuplicateNameException if a user with the same username already exists
 577          * @throws ObjectNotFoundException if no username was provided
 578          */
 579         public User createUser(String username, String name, String mail,
 580                                 String persistentId) throws DuplicateNameException,
 581                                 ObjectNotFoundException;
 582
 583         /**
 584          * Updates the authentication token for the specified user.
 585          *
 586          * @param userId the ID of the user whose token should be updated
 587          * @return the updated user
 588          * @throws ObjectNotFoundException if the user could not be found
 589          */
 590         public User updateUserToken(Long userId) throws ObjectNotFoundException;
 591
 592         /**
 593          * Invalidates the authentication token for the specified user.
 594          *
 595          * @param userId the ID of the user whose token should be updated
 596          * @throws ObjectNotFoundException if the user could not be found
 597          */
 598         public void invalidateUserToken(Long userId) throws ObjectNotFoundException;
 599
 600         /**
 601          * Retrieve folder user and group permissions
 602          *
 603          * @param userId the ID of the user whose token should be updated
 604          * @param folderId the ID of the folder
 605          * @return the Set of permissions from requested folder
 606          * @throws ObjectNotFoundException if the user or folder could not be found
 607          * @throws InsufficientPermissionsException
 608          */
 609         public Set<PermissionDTO> getFolderPermissions(Long userId, Long folderId) throws ObjectNotFoundException, InsufficientPermissionsException;
 610
 611         /**
 612          * Retrieve file user and group permissions
 613          *
 614          * @param userId the ID of the user whose token should be updated
 615          * @param fileId the ID of the folder
 616          * @return the Set of permissions from requested folder
 617          * @throws ObjectNotFoundException if the user or folder could not be found
 618          * @throws InsufficientPermissionsException
 619          */
 620         public Set<PermissionDTO> getFilePermissions(Long userId, Long fileId) throws ObjectNotFoundException, InsufficientPermissionsException;
 621
 622         /**
 623          * Returns a list of All Shared root folders of a user.
 624          *
 625          * @param userId the ID of the User
 626          *       * @return the list of shared root folders
 627          * @throws ObjectNotFoundException if the user cannot be found
 628          */
 629         public List<FolderDTO> getSharedRootFolders(Long userId) throws ObjectNotFoundException;
 630
 631         /**
 632          * Returns a list of All Shared  files of a user.
 633          *
 634          * @param userId the ID of the User
 635          *       * @return the list of shared files
 636          * @throws ObjectNotFoundException if the user cannot be found
 637          */
 638         public List<FileHeaderDTO> getSharedFilesNotInSharedFolders(Long userId) throws ObjectNotFoundException;
 639
 640         /**
 641          * Returns a list of All Shared root folders of a user that calling user has at least read permissions.
 642          *
 643          * @param ownerId the ID of the User
 644          * @return the list of shared root folders
 645          * @param callingUserId
 646          *
 647          * @throws ObjectNotFoundException if the user cannot be found
 648          */
 649         public List<FolderDTO> getSharedRootFolders(Long ownerId, Long callingUserId) throws ObjectNotFoundException;
 650
 651         /**
 652          * Returns a list of All Shared  files of a user that calling user has at least read permissions..
 653          *
 654          * @param ownerId the ID of the User
 655          * @return the list of shared files
 656          * @param callingUserId
 657          * @throws ObjectNotFoundException if the user cannot be found
 658          */
 659         public List<FileHeaderDTO> getSharedFiles(Long ownerId, Long callingUserId) throws ObjectNotFoundException;
 660
 661         /**
 662          * Remove a user member from a group
 663          *
 664          * @param userId the ID of the User owning the group
 665          * @param groupId the ID of the requested group
 666          * @param memberId the ID of the member to be removed
 667          *
 668          * @throws ObjectNotFoundException if the user or group was not found, with
 669          *             the exception message mentioning the precise problem
 670          * @throws InsufficientPermissionsException
 671          */
 672         public void removeMemberFromGroup(Long userId, Long groupId, Long memberId) throws ObjectNotFoundException, InsufficientPermissionsException;
 673
 674         /**
 675          * Retrieves the list of users sharing files to user identified by user id
 676          * @param userId
 677          * @return the List of users sharing files to user
 678          * @throws ObjectNotFoundException
 679          */
 680         public List<UserDTO> getUsersSharingFoldersForUser(Long userId) throws ObjectNotFoundException;
 681
 682         /**
 683          * Indexes the file meta-data and contents. It actually sends the info to be indexed to a message queue
 684          * and the actual indexing will be done in the background
 685          *
 686          * @param fileId The id of the file to be indexed. The message processor will retreive all file data
 687          * by using this id
 688          * @param delete if true the file is removed from the index
 689          */
 690         public void indexFile(Long fileId, boolean delete);
 691
 692         /**
 693          * Search Files
 694          *
 695          * @param userId
 696          * @param query
 697          * @return list of files that match query
 698          * @throws ObjectNotFoundException
 699          */
 700         public List<FileHeaderDTO> searchFiles(Long userId, String query) throws ObjectNotFoundException;
 701
 702         /**
 703          * It is used by the Solr mbean to rebuild the index.
 704          */
 705         public void rebuildSolrIndex();
 706
 707         /**
 708          * Search the system for a user with the specified email address.
 709          * If no such user is found, the method returns null.
 710          */
 711         public User findUserByEmail(String email);
 712
 713         /**
 714          * Update the user with the values from the supplied object.
 715          */
 716         public void updateUser(User user);
 717
 718         /**
 719          * Check if the user with the specified ID has permission to read the
 720          * folder with the supplied ID.
 721          */
 722         public boolean canReadFolder(Long userId, Long folderId) throws ObjectNotFoundException;
 723 }