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 ObjectNotFoundException
 308          * @throws InsufficientPermissionsException
 309          */
 310         public void updateFile(Long userId, Long fileId, String name, String tagSet,
 311                         Date modificationDate, Boolean versioned, Boolean readForAll,
 312                         Set<PermissionDTO> permissions)
 313                         throws ObjectNotFoundException, InsufficientPermissionsException;
 314
 315         /**
 316          * Retrieve the contents of the current body for the file
 317          * with the specified FileHeader ID. The file contents
 318          * are provided as an InputStream from which the caller can
 319          * retrieve the raw bytes.
 320          *
 321          * @param userId the ID of the current user
 322          * @param fileId the ID of the file to retrieve
 323          * @return an InputStream from the current file body contents
 324          * @throws ObjectNotFoundException if the file or the user was not found
 325          * @throws InsufficientPermissionsException  if the user does not have the
 326          *             appropriate privileges
 327          */
 328         public InputStream getFileContents(Long userId, Long fileId) throws ObjectNotFoundException, InsufficientPermissionsException;
 329
 330         /**
 331          * Retrieve the file with the specified ID.
 332          *
 333          * @param userId the ID of the current user
 334          * @param fileId the ID of the file to retrieve
 335          * @return the file found
 336          * @throws ObjectNotFoundException if the file or the user was not found, with
 337          *                      the exception message mentioning the precise problem
 338          * @throws InsufficientPermissionsException
 339          */
 340         public FileHeaderDTO getFile(Long userId, Long fileId) throws ObjectNotFoundException, InsufficientPermissionsException;
 341
 342         /**
 343          * Get the resource (file or folder) at the specified path in
 344          * the specified user's namespace. The returned object will be of type
 345          * FileHeaderDTO or FolderDTO.<p><strong>Note:</strong> this method does not
 346          * receive the current user as a parameter, therefore it is unable to perform
 347          * the necessary permission checks and should <strong>NOT</strong> be directly
 348          * exposed to remote clients. It is the caller's responsibility to verify that
 349          * the calling user has the required privileges for performing any subsequent
 350          * action on the resource through one of the other ExternalAPI methods.
 351          *
 352          * @param ownerId the ID of the user owning the namespace
 353          * @param path the absolute path in the user's namespace
 354          * @param ignoreDeleted if true, resources that have been moved to the trash
 355          *                      will be ignored
 356          * @throws ObjectNotFoundException if the user or resource was not found, with
 357          *                      the exception message mentioning the precise problem
 358          * @return the resource found
 359          */
 360         public Object getResourceAtPath(Long ownerId, String path, boolean ignoreDeleted)
 361                         throws ObjectNotFoundException;
 362
 363         /**
 364          * Copy the provided file to the specified destination.
 365          *
 366          * @param userId the ID of the current user
 367          * @param fileId the IF of the provided file
 368          * @param dest the path to the destination folder
 369          * @throws ObjectNotFoundException if the user, file or destination was not
 370          *                      found, with     the exception message mentioning the precise problem
 371          * @throws GSSIOException if there was an error while accessing the file contents
 372          * @throws DuplicateNameException if the specified name already exists in
 373          *          the destination folder, as either a folder or file
 374          * @throws InsufficientPermissionsException
 375          */
 376         public void copyFile(Long userId, Long fileId, String dest) throws ObjectNotFoundException, DuplicateNameException, GSSIOException, InsufficientPermissionsException, QuotaExceededException;
 377
 378         /**
 379          * Copy the provided file to the specified destination.
 380          *
 381          * @param userId the ID of the current user
 382          * @param fileId the IF of the provided file
 383          * @param destId the ID of the destination folder
 384          * @param destName the name of the new file
 385          * @throws ObjectNotFoundException if the user, file or destination was not
 386          *                      found, with     the exception message mentioning the precise problem
 387          * @throws GSSIOException if there was an error while accessing the file contents
 388          * @throws DuplicateNameException if the specified name already exists in
 389          *          the destination folder, as either a folder or file
 390          * @throws InsufficientPermissionsException
 391          */
 392         public void copyFile(Long userId, Long fileId, Long destId, String destName) throws ObjectNotFoundException, DuplicateNameException, GSSIOException, InsufficientPermissionsException, QuotaExceededException;
 393
 394         /**
 395          * Copy the provided folder to the specified destination.
 396          *
 397          * @param userId the ID of the current user
 398          * @param folderId the IF of the provided folder
 399          * @param dest the path to the destination folder
 400          * @throws ObjectNotFoundException if the user, folder or destination was not
 401          *                      found, with     the exception message mentioning the precise problem
 402          * @throws DuplicateNameException if the specified name already exists in
 403          *          the destination folder, as either a folder or file
 404          * @throws InsufficientPermissionsException InsufficientPermissionsException if the user does not have the
 405          *          appropriate privileges
 406          */
 407         public void copyFolder(Long userId, Long folderId, String dest) throws ObjectNotFoundException, DuplicateNameException, InsufficientPermissionsException, QuotaExceededException;
 408
 409         /**
 410          * Copy the provided folder to the specified destination.
 411          *
 412          * @param userId the ID of the current user
 413          * @param folderId the IF of the provided folder
 414          * @param destId the ID of the destination folder
 415          * @param destName the name of the new folder
 416          * @throws ObjectNotFoundException if the user, folder or destination was not
 417          *                      found, with     the exception message mentioning the precise problem
 418          * @throws DuplicateNameException if the specified name already exists in
 419          *          the destination folder, as either a folder or file
 420          * @throws InsufficientPermissionsException InsufficientPermissionsException if the user does not have the
 421          *          appropriate privileges
 422          */
 423         public void copyFolder(Long userId, Long folderId, Long destId, String destName) throws ObjectNotFoundException, DuplicateNameException, InsufficientPermissionsException, QuotaExceededException;
 424
 425         /**
 426          * Copy the provided folder and all its subfolders and files to the specified destination.
 427          *
 428          * @param userId the ID of the current user
 429          * @param folderId the IF of the provided folder
 430          * @param destId the ID of the destination folder
 431          * @param destName the name of the new folder
 432          * @throws ObjectNotFoundException if the user, folder or destination was not
 433          *                      found, with     the exception message mentioning the precise problem
 434          * @throws DuplicateNameException if the specified name already exists in
 435          *          the destination folder, as either a folder or file
 436          * @throws InsufficientPermissionsException InsufficientPermissionsException if the user does not have the
 437          *          appropriate privileges
 438          * @throws GSSIOException
 439          */
 440         public void copyFolderStructure(Long userId, Long folderId, Long destId, String destName) throws ObjectNotFoundException, DuplicateNameException, InsufficientPermissionsException,GSSIOException, QuotaExceededException;
 441
 442         /**
 443          * Marks  the specified file as deleted in the specified user's namespace.
 444          *
 445          * @param userId the ID of the current user
 446          * @param fileId the ID of the file to delete
 447          * @throws ObjectNotFoundException if the user or file was not found, with
 448          *             the exception message mentioning the precise problem
 449          * @throws InsufficientPermissionsException if the user does not have the
 450          *             appropriate privileges
 451          */
 452         public void moveFileToTrash(Long userId, Long fileId) throws ObjectNotFoundException, InsufficientPermissionsException;
 453
 454         /**
 455          * Marks  the specified deleted file as undeleted in the specified user's namespace.
 456          *
 457          * @param userId the ID of the current user
 458          * @param fileId the ID of the file to undelete
 459          * @throws ObjectNotFoundException if the user or file was not found, with
 460          *             the exception message mentioning the precise problem
 461          * @throws InsufficientPermissionsException if the user does not have the
 462          *             appropriate privileges
 463          */
 464         public void removeFileFromTrash(Long userId, Long fileId) throws ObjectNotFoundException, InsufficientPermissionsException;
 465
 466         /**
 467          * Marks  the specified folder as deleted in the specified user's namespace.
 468          *
 469          * @param userId the ID of the current user
 470          * @param folderId the ID of the folder to delete
 471          * @throws ObjectNotFoundException if the user or file was not found, with
 472          *             the exception message mentioning the precise problem
 473          * @throws InsufficientPermissionsException if the user does not have the
 474          *             appropriate privileges
 475          */
 476         public void moveFolderToTrash(Long userId, Long folderId) throws ObjectNotFoundException, InsufficientPermissionsException;
 477
 478         /**
 479          * Marks  the specified deleted folder as undeleted in the specified user's namespace.
 480          *
 481          * @param userId the ID of the current user
 482          * @param folderId the ID of the folder to undelete
 483          * @throws ObjectNotFoundException if the user or file was not found, with
 484          *             the exception message mentioning the precise problem
 485          * @throws InsufficientPermissionsException if the user does not have the
 486          *             appropriate privileges
 487          */
 488         public void removeFolderFromTrash(Long userId, Long folderId) throws ObjectNotFoundException, InsufficientPermissionsException;
 489
 490         /**
 491          * Move the provided folder and all its subfolders and files to the specified destination.
 492          *
 493          * @param userId the ID of the current user
 494          * @param folderId the IF of the provided folder
 495          * @param destId the ID of the destination folder
 496          * @param destName the name of the new folder
 497          * @throws ObjectNotFoundException if the user, folder or destination was not
 498          *                      found, with     the exception message mentioning the precise problem
 499          * @throws DuplicateNameException if the specified name already exists in
 500          *          the destination folder, as either a folder or file
 501          * @throws InsufficientPermissionsException if the user does not have the
 502          *          appropriate privileges
 503          * @throws GSSIOException
 504          */
 505         public void moveFolder(Long userId, Long folderId, Long destId, String destName) throws ObjectNotFoundException, DuplicateNameException, InsufficientPermissionsException, GSSIOException, QuotaExceededException;
 506
 507         /**
 508          * move the provided file to the specified destination.
 509          *
 510          * @param userId the ID of the current user
 511          * @param fileId the IF of the provided file
 512          * @param destId the ID of the destination folder
 513          * @param destName the name of the new file
 514          * @throws InsufficientPermissionsException
 515          * @throws ObjectNotFoundException if the user, file or destination was not
 516          *                      found, with     the exception message mentioning the precise problem
 517          * @throws GSSIOException if there was an error while accessing the file contents
 518          * @throws DuplicateNameException if the specified name already exists in
 519          *          the destination folder, as either a folder or file
 520          */
 521         public void moveFile(Long userId, Long fileId, Long destId, String destName) throws InsufficientPermissionsException, ObjectNotFoundException, DuplicateNameException, GSSIOException, QuotaExceededException;
 522
 523         /**
 524          * Returns a list of All deleted files of a user.
 525          *
 526          * @param userId the ID of the User
 527          *       * @return the list of deleted file header objects
 528          * @throws ObjectNotFoundException if the user cannot be found
 529          */
 530         public List<FileHeaderDTO> getDeletedFiles(Long userId) throws ObjectNotFoundException;
 531
 532         /**
 533          * Returns a list of All deleted root folders of a user.
 534          *
 535          * @param userId the ID of the User
 536          *       * @return the list of deleted file header objects
 537          * @throws ObjectNotFoundException if the user cannot be found
 538          */
 539         public List<FolderDTO> getDeletedRootFolders(Long userId) throws ObjectNotFoundException;
 540
 541         /**
 542          * Empty Trash by deleting all marked as deleted files and folders
 543          * @param userId
 544          * @throws ObjectNotFoundException if something goes wrong in the delete process
 545          * @throws InsufficientPermissionsException  if something goes wrong in the delete process
 546          */
 547         public void emptyTrash(Long userId) throws ObjectNotFoundException, InsufficientPermissionsException;
 548
 549         /**
 550          * Restores All Trashed Items by undeleting all marked as deleted files and folders
 551          * @param userId
 552          * @throws ObjectNotFoundException if something goes wrong in the delete process
 553          * @throws InsufficientPermissionsException if the user does not have the
 554          *          appropriate privileges
 555          */
 556         public void restoreTrash(Long userId) throws ObjectNotFoundException, InsufficientPermissionsException;
 557
 558         /**
 559          * Search the system for a user with the specified username.
 560          * If no such user is found, the method returns null.
 561          *
 562          * @param username the username to search for
 563          * @return the User object with the specified username
 564          */
 565         public User findUser(String username);
 566
 567         /**
 568          * Create a new user with the specified name, username and e-mail address.
 569          *
 570          * @param username the username of the new user
 571          * @param name the full name of the new user
 572          * @param mail the e-mail of the new user
 573          * @return the newly-created User object
 574          * @throws DuplicateNameException if a user with the same username already exists
 575          * @throws ObjectNotFoundException if no username was provided
 576          */
 577         public User createUser(String username, String name, String mail) throws DuplicateNameException, ObjectNotFoundException;
 578
 579         /**
 580          * Updates the authentication token for the specified user.
 581          *
 582          * @param userId the ID of the user whose token should be updated
 583          * @return the updated user
 584          * @throws ObjectNotFoundException if the user could not be found
 585          */
 586         public User updateUserToken(Long userId) throws ObjectNotFoundException;
 587
 588         /**
 589          * Invalidates the authentication token for the specified user.
 590          *
 591          * @param userId the ID of the user whose token should be updated
 592          * @throws ObjectNotFoundException if the user could not be found
 593          */
 594         public void invalidateUserToken(Long userId) throws ObjectNotFoundException;
 595
 596         /**
 597          * Retrieve folder user and group permissions
 598          *
 599          * @param userId the ID of the user whose token should be updated
 600          * @param folderId the ID of the folder
 601          * @return the Set of permissions from requested folder
 602          * @throws ObjectNotFoundException if the user or folder could not be found
 603          * @throws InsufficientPermissionsException
 604          */
 605         public Set<PermissionDTO> getFolderPermissions(Long userId, Long folderId) throws ObjectNotFoundException, InsufficientPermissionsException;
 606
 607         /**
 608          * Retrieve file user and group permissions
 609          *
 610          * @param userId the ID of the user whose token should be updated
 611          * @param fileId the ID of the folder
 612          * @return the Set of permissions from requested folder
 613          * @throws ObjectNotFoundException if the user or folder could not be found
 614          * @throws InsufficientPermissionsException
 615          */
 616         public Set<PermissionDTO> getFilePermissions(Long userId, Long fileId) throws ObjectNotFoundException, InsufficientPermissionsException;
 617
 618         /**
 619          * Returns a list of All Shared root folders of a user.
 620          *
 621          * @param userId the ID of the User
 622          *       * @return the list of shared root folders
 623          * @throws ObjectNotFoundException if the user cannot be found
 624          */
 625         public List<FolderDTO> getSharedRootFolders(Long userId) throws ObjectNotFoundException;
 626
 627         /**
 628          * Returns a list of All Shared  files of a user.
 629          *
 630          * @param userId the ID of the User
 631          *       * @return the list of shared files
 632          * @throws ObjectNotFoundException if the user cannot be found
 633          */
 634         public List<FileHeaderDTO> getSharedFilesNotInSharedFolders(Long userId) throws ObjectNotFoundException;
 635
 636         /**
 637          * Returns a list of All Shared root folders of a user that calling user has at least read permissions.
 638          *
 639          * @param ownerId the ID of the User
 640          * @return the list of shared root folders
 641          * @param callingUserId
 642          *
 643          * @throws ObjectNotFoundException if the user cannot be found
 644          */
 645         public List<FolderDTO> getSharedRootFolders(Long ownerId, Long callingUserId) throws ObjectNotFoundException;
 646
 647         /**
 648          * Returns a list of All Shared  files of a user that calling user has at least read permissions..
 649          *
 650          * @param ownerId the ID of the User
 651          * @return the list of shared files
 652          * @param callingUserId
 653          * @throws ObjectNotFoundException if the user cannot be found
 654          */
 655         public List<FileHeaderDTO> getSharedFiles(Long ownerId, Long callingUserId) throws ObjectNotFoundException;
 656
 657         /**
 658          * Remove a user member from a group
 659          *
 660          * @param userId the ID of the User owning the group
 661          * @param groupId the ID of the requested group
 662          * @param memberId the ID of the member to be removed
 663          *
 664          * @throws ObjectNotFoundException if the user or group was not found, with
 665          *             the exception message mentioning the precise problem
 666          * @throws InsufficientPermissionsException
 667          */
 668         public void removeMemberFromGroup(Long userId, Long groupId, Long memberId) throws ObjectNotFoundException, InsufficientPermissionsException;
 669
 670         /**
 671          * Retrieves the list of users sharing files to user identified by user id
 672          * @param userId
 673          * @return the List of users sharing files to user
 674          * @throws ObjectNotFoundException
 675          */
 676         public List<UserDTO> getUsersSharingFoldersForUser(Long userId) throws ObjectNotFoundException;
 677
 678         /**
 679          * Indexes the file meta-data and contents. It actually sends the info to be indexed to a message queue
 680          * and the actual indexing will be done in the background
 681          *
 682          * @param fileId The id of the file to be indexed. The message processor will retreive all file data
 683          * by using this id
 684          * @param delete if true the file is removed from the index
 685          */
 686         public void indexFile(Long fileId, boolean delete);
 687
 688         /**
 689          * Search Files
 690          *
 691          * @param userId
 692          * @param query
 693          * @return list of files that match query
 694          * @throws ObjectNotFoundException
 695          */
 696         public List<FileHeaderDTO> searchFiles(Long userId, String query) throws ObjectNotFoundException;
 697
 698         /**
 699          * It is used by the Solr mbean to rebuild the index.
 700          */
 701         public void rebuildSolrIndex();
 702
 703         /**
 704          * Search the system for a user with the specified email address.
 705          * If no such user is found, the method returns null.
 706          */
 707         public User findUserByEmail(String email);
 708
 709         /**
 710          * Update the user with the values from the supplied object.
 711          */
 712         public void updateUser(User user);
 713
 714         /**
 715          * Check if the user with the specified ID has permission to read the
 716          * folder with the supplied ID.
 717          */
 718         public boolean canReadFolder(Long userId, Long folderId) throws ObjectNotFoundException;
 719 }