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