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

   1 /*
   2  * Copyright 2007, 2008, 2009, 2010 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.InvitationUsedException;
  25 import gr.ebs.gss.client.exceptions.ObjectNotFoundException;
  26 import gr.ebs.gss.client.exceptions.QuotaExceededException;
  27 import gr.ebs.gss.server.domain.FileBody;
  28 import gr.ebs.gss.server.domain.FileHeader;
  29 import gr.ebs.gss.server.domain.FileUploadStatus;
  30 import gr.ebs.gss.server.domain.Folder;
  31 import gr.ebs.gss.server.domain.Group;
  32 import gr.ebs.gss.server.domain.Invitation;
  33 import gr.ebs.gss.server.domain.Nonce;
  34 import gr.ebs.gss.server.domain.Permission;
  35 import gr.ebs.gss.server.domain.User;
  36 import gr.ebs.gss.server.domain.UserClass;
  37 import gr.ebs.gss.server.domain.UserLogin;
  38 import gr.ebs.gss.server.domain.dto.StatsDTO;
  39 import gr.ebs.gss.server.domain.dto.UserDTO;
  40
  41 import java.io.File;
  42 import java.io.IOException;
  43 import java.io.InputStream;
  44 import java.util.Date;
  45 import java.util.List;
  46 import java.util.Set;
  47
  48 import javax.ejb.Local;
  49 import javax.ejb.TransactionAttribute;
  50 import javax.ejb.TransactionAttributeType;
  51
  52 import org.apache.solr.client.solrj.impl.CommonsHttpSolrServer;
  53
  54 /**
  55  * The External API for GSS clients.
  56  *
  57  * @author past
  58  */
  59 @Local
  60 public interface ExternalAPI {
  61
  62         /**
  63          * Retrieves the root folder for the specified user. The caller must ensure
  64          * that the userId exists.
  65          *
  66          * @param userId
  67          * @return Folder
  68          * @throws ObjectNotFoundException if no Folder or user was found
  69          */
  70         public Folder getRootFolder(Long userId) throws ObjectNotFoundException;
  71
  72         /**
  73          * Retrieve the folder with the specified ID.
  74          *
  75          * @param userId the ID of the current user
  76          * @param folderId the ID of the folder to retrieve
  77          * @return the folder found
  78          * @throws ObjectNotFoundException if the folder or the user was not found
  79          * @throws InsufficientPermissionsException if ther user does not have read permissions for folder
  80          */
  81         public Folder getFolder(Long userId, Long folderId) throws ObjectNotFoundException,
  82                         InsufficientPermissionsException;
  83
  84         /**
  85          * Returns the user with the specified ID.
  86          *
  87          * @param userId The ID of the User to be found
  88          * @return The User object
  89          * @throws ObjectNotFoundException if the user cannot be found
  90          */
  91         public User getUser(Long userId) throws ObjectNotFoundException;
  92
  93         /**
  94          * Returns the user with the specified ID.
  95          *
  96          * @param userId The ID of the User to be found
  97          * @return The User object
  98          * @throws ObjectNotFoundException if the user cannot be found
  99          */
 100         public UserDTO getUserDTO(Long userId) throws ObjectNotFoundException;
 101
 102         /**
 103          * Returns the group with the specified ID.
 104          *
 105          * @param groupId The ID of the Group to be found
 106          * @return The Group object
 107          * @throws ObjectNotFoundException if the group cannot be found
 108          */
 109         public Group getGroup(Long groupId) throws ObjectNotFoundException;
 110
 111         /**
 112          * Returns the group with the specified name that belongs to the
 113          * specified user.
 114          *
 115          * @param userId the ID of the user
 116          * @param name the name of the group
 117          * @return The Group object
 118          * @throws ObjectNotFoundException if the group cannot be found
 119          */
 120         public Group getGroup(Long userId, String name) throws ObjectNotFoundException;
 121
 122         /**
 123          * Retrieve the list of groups for a particular user.
 124          *
 125          * @param userId the ID of the User
 126          * @return a List of Groups that belong to the specified User
 127          * @throws ObjectNotFoundException if the user was not found
 128          */
 129         public List<Group> getGroups(Long userId) throws ObjectNotFoundException;
 130
 131         /**
 132          * Returns a list of files contained in the folder specified by its id.
 133          *
 134          * @param userId the ID of the User
 135          * @param folderId the ID of the folder containing the files
 136          * @param ignoreDeleted
 137          * @return the list of file header objects
 138          * @throws ObjectNotFoundException if the user or the folder cannot be found
 139          * @throws InsufficientPermissionsException
 140          */
 141         public List<FileHeader> getFiles(Long userId, Long folderId, boolean ignoreDeleted) throws ObjectNotFoundException,
 142                         InsufficientPermissionsException;
 143
 144         /**
 145          * Returns a list of users for the specified group
 146          *
 147          * @param userId the ID of the User
 148          * @param groupId the ID of the requested group
 149          * @return List<User>
 150          * @throws ObjectNotFoundException if the user or group was not found, with
 151          *             the exception message mentioning the precise problem
 152          */
 153         public List<User> getUsers(Long userId, Long groupId) throws ObjectNotFoundException;
 154
 155         /**
 156          * Returns a list of users matching the specified username
 157          *
 158          * @param username the username of the User
 159          * @return List<User>
 160          */
 161         public List<User> getUsersByUserNameLike(String username);
 162
 163         /**
 164          * Creates a new folder with the specified owner, parent folder and name.
 165          * New folder has the same permissions as its parent
 166          *
 167          * @param userId
 168          * @param parentId
 169          * @param name
 170          * @return the new folder
 171          * @throws DuplicateNameException if the specified name already exists in
 172          *             the parent folder, as either a folder or file
 173          * @throws ObjectNotFoundException if the user or parent folder was not
 174          *             found, with the exception message mentioning the precise
 175          *             problem
 176          * @throws InsufficientPermissionsException
 177          */
 178         public Folder createFolder(Long userId, Long parentId, String name) throws DuplicateNameException,
 179                         ObjectNotFoundException, InsufficientPermissionsException;
 180
 181         /**
 182          * Deletes the specified folder, if the specified user has the appropriate
 183          * permission.
 184          *
 185          * @param userId the ID of the current user
 186          * @param folderId the ID of the folder to delete
 187          * @throws InsufficientPermissionsException if the user does not have the
 188          *             appropriate privileges
 189          * @throws ObjectNotFoundException if the user or folder was not found, with
 190          *             the exception message mentioning the precise problem
 191          */
 192         public void deleteFolder(Long userId, Long folderId)
 193                         throws InsufficientPermissionsException, ObjectNotFoundException;
 194
 195         /**
 196          * Retrieve the subfolders of the specified folder.
 197          *
 198          * @param userId the ID of the current user
 199          * @param folderId the ID of the folder to retrieve
 200          * @return the list of subfolders found
 201          * @throws ObjectNotFoundException if the folder or user was not found
 202          * @throws InsufficientPermissionsException
 203          */
 204         public List<Folder> getSubfolders(Long userId, Long folderId)
 205                         throws ObjectNotFoundException, InsufficientPermissionsException;
 206
 207         /**
 208          * Retrieve the subfolders of the specified folder that are shared to others.
 209          *
 210          * @param userId the ID of the current user
 211          * @param folderId the ID of the folder to retrieve
 212          * @return the list of subfolders found
 213          * @throws ObjectNotFoundException if the folder or user was not found
 214          */
 215         public List<Folder> getSharedSubfolders(Long userId, Long folderId) throws ObjectNotFoundException;
 216
 217         /**
 218          * Retrieve the subfolders of the specified folder that are shared to others.
 219          *
 220          * @param userId the ID of the current user
 221          * @param callingUserId the id of the user requesting this operation
 222          * @param folderId the ID of the folder to retrieve
 223          * @return the list of subfolders found
 224          * @throws ObjectNotFoundException if the folder or user was not found
 225          */
 226         public List<Folder> getSharedSubfolders(Long userId, Long callingUserId, Long folderId) throws ObjectNotFoundException;
 227         /**
 228          * Modifies the specified folder if the specified user has the appropriate
 229          * permission.
 230          *
 231          * @param userId the ID of the current user
 232          * @param folderId the ID of the folder to retrieve
 233          * @param folderName
 234          * @param readForAll
 235          * @param permissions
 236          * @return the updated folder
 237          * @throws InsufficientPermissionsException if the user does not have the
 238          *             appropriate privileges
 239          * @throws ObjectNotFoundException if the user or folder was not found, with
 240          *             the exception message mentioning the precise problem
 241          * @throws DuplicateNameException if the specified name already exists in
 242          *             the parent folder, as either a folder or file
 243          */
 244         public Folder updateFolder(Long userId, Long folderId, String folderName,
 245                                 Boolean readForAll,
 246                                 Set<Permission> permissions)
 247                         throws InsufficientPermissionsException, ObjectNotFoundException, DuplicateNameException;
 248
 249         /**
 250          * Adds a user to the specified group
 251          *
 252          * @param userId the ID of the current user
 253          * @param groupId the id of the new group
 254          * @param userToAddId the id of the user to add
 255          * @throws DuplicateNameException if the user already exists in group
 256          * @throws ObjectNotFoundException if the user or group was not found, with
 257          *             the exception message mentioning the precise problem
 258          * @throws InsufficientPermissionsException
 259          */
 260         public void addUserToGroup(Long userId, Long groupId, Long userToAddId)
 261                         throws ObjectNotFoundException, DuplicateNameException, InsufficientPermissionsException;
 262
 263         /**
 264          * Creates a new group with the specified owner and name.
 265          *
 266          * @param userId the ID of the current user
 267          * @param name the name of the new group
 268          * @throws DuplicateNameException if the new group name already exists
 269          * @throws ObjectNotFoundException if the user or group was not found, with
 270          *             the exception message mentioning the precise problem
 271          */
 272         public void createGroup(Long userId, String name) throws ObjectNotFoundException, DuplicateNameException;
 273
 274         /**
 275          * Deletes the specified group in the specified user's namespace.
 276          *
 277          * @param userId the ID of the current user
 278          * @param groupId the ID of the group to delete
 279          * @throws ObjectNotFoundException if the user or group was not found, with
 280          *             the exception message mentioning the precise problem
 281          * @throws InsufficientPermissionsException
 282          */
 283         public void deleteGroup(Long userId, Long groupId) throws ObjectNotFoundException, InsufficientPermissionsException;
 284
 285         /**
 286          * Creates a new file with the specified owner, parent folder and name. The
 287          * new file has the same permissions as its parent folder. The file contents
 288          * are read from the input stream to a new File object.
 289          *
 290          * @param userId the ID of the current user
 291          * @param folderId the ID of the parent folder
 292          * @param name the name of the new file
 293          * @param mimeType the MIME type of the file
 294          * @param stream the input stream with the file contents
 295          * @return The FileHeader created
 296          * @throws DuplicateNameException if the specified name already exists in
 297          *             the parent folder, as either a folder or file
 298          * @throws ObjectNotFoundException if the user or parent folder was not
 299          *             found, with the exception message mentioning the precise
 300          *             problem
 301          * @throws GSSIOException if there was an error while storing the file contents
 302          * @throws InsufficientPermissionsException
 303          * @throws QuotaExceededException
 304          */
 305         public FileHeader createFile(Long userId, Long folderId, String name, String mimeType,
 306                                 InputStream stream) throws DuplicateNameException, ObjectNotFoundException,
 307                                 GSSIOException, InsufficientPermissionsException, QuotaExceededException;
 308
 309         /**
 310          * Deletes the specified file, provided the specified user has
 311          * the necessary permissions.
 312          *
 313          * @param userId the ID of the current user
 314          * @param fileId the ID of the file to delete
 315          * @throws ObjectNotFoundException if the user or file was not found, with
 316          *             the exception message mentioning the precise problem
 317          * @throws InsufficientPermissionsException if the user does not have the
 318          *             appropriate privileges
 319          */
 320         public void deleteFile(Long userId, Long fileId) throws ObjectNotFoundException, InsufficientPermissionsException;
 321
 322         /**
 323          * Creates a new tag for the specified user and file.
 324          *
 325          * @param userId the creator of the tag
 326          * @param fileHeaderId the file that is tagged
 327          * @param tag the tag
 328          * @throws ObjectNotFoundException if the user or the file was not found
 329          */
 330         public void createTag(Long userId, Long fileHeaderId, String tag) throws ObjectNotFoundException;
 331
 332         /**
 333          * Returns all tags defined by the specified user
 334          *
 335          * @param userId
 336          * @return Set<String>
 337          * @throws ObjectNotFoundException if the user was null
 338          */
 339         public Set<String> getUserTags(final Long userId) throws ObjectNotFoundException;
 340
 341         /**
 342          * Updates the attributes of the specified file.
 343          *
 344          * @param userId
 345          * @param fileId
 346          * @param name
 347          * @param tagSet a String that contains tags separated by comma
 348          * @param modificationDate the modification date
 349          * @param versioned the new value of the versioned flag
 350          * @param readForAll
 351          * @param permissions
 352          * @throws DuplicateNameException
 353          * @throws ObjectNotFoundException
 354          * @throws InsufficientPermissionsException
 355          */
 356         public void updateFile(Long userId, Long fileId, String name, String tagSet,
 357                         Date modificationDate, Boolean versioned, Boolean readForAll,
 358                         Set<Permission> permissions)
 359                         throws DuplicateNameException, ObjectNotFoundException, InsufficientPermissionsException;
 360
 361         /**
 362          * Retrieve the contents of the current body for the file
 363          * with the specified FileHeader ID. The file contents
 364          * are provided as an InputStream from which the caller can
 365          * retrieve the raw bytes.
 366          *
 367          * @param userId the ID of the current user
 368          * @param fileId the ID of the file to retrieve
 369          * @return an InputStream from the current file body contents
 370          * @throws ObjectNotFoundException if the file or the user was not found
 371          * @throws InsufficientPermissionsException  if the user does not have the
 372          *             appropriate privileges
 373          */
 374         public InputStream getFileContents(Long userId, Long fileId)
 375                         throws ObjectNotFoundException, InsufficientPermissionsException;
 376
 377         /**
 378          * Retrieve the contents of the  body identified by bodyId for the file
 379          * with the specified FileHeader ID. The file contents
 380          * are provided as an InputStream from which the caller can
 381          * retrieve the raw bytes.
 382          *
 383          * @param userId the ID of the current user
 384          * @param fileId the ID of the file to retrieve
 385          * @param bodyId the body ID
 386          * @return an InputStream from the current file body contents
 387          * @throws ObjectNotFoundException if the file or the user was not found
 388          * @throws InsufficientPermissionsException  if the user does not have the
 389          *             appropriate privileges
 390          */
 391         public InputStream getFileContents(Long userId, Long fileId, Long bodyId)
 392                         throws ObjectNotFoundException, InsufficientPermissionsException;
 393
 394         /**
 395          * Retrieve the file with the specified ID.
 396          *
 397          * @param userId the ID of the current user
 398          * @param fileId the ID of the file to retrieve
 399          * @return the file found
 400          * @throws ObjectNotFoundException if the file or the user was not found, with
 401          *                      the exception message mentioning the precise problem
 402          * @throws InsufficientPermissionsException
 403          */
 404         public FileHeader getFile(Long userId, Long fileId) throws ObjectNotFoundException,
 405                         InsufficientPermissionsException;
 406
 407         /**
 408          * Retrieve the filebody with the specified ID.
 409          *
 410          * @param userId the ID of the current user
 411          * @param fileId the ID of the file to retrieve
 412          * @param bodyId the ID of the body
 413          * @return the file found
 414          * @throws ObjectNotFoundException if the file or the user was not found, with
 415          *                      the exception message mentioning the precise problem
 416          * @throws InsufficientPermissionsException
 417          */
 418         public FileBody getFileBody(Long userId, Long fileId, Long bodyId)
 419                         throws ObjectNotFoundException, InsufficientPermissionsException;
 420
 421         /**
 422          * Get the resource (file or folder) at the specified path in
 423          * the specified user's namespace. The returned object will be of type
 424          * FileHeader or Folder.<p><strong>Note:</strong> this method does not
 425          * receive the current user as a parameter, therefore it is unable to perform
 426          * the necessary permission checks and should <strong>NOT</strong> be directly
 427          * exposed to remote clients. It is the caller's responsibility to verify that
 428          * the calling user has the required privileges for performing any subsequent
 429          * action on the resource through one of the other ExternalAPI methods.
 430          *
 431          * @param ownerId the ID of the user owning the namespace
 432          * @param path the absolute path in the user's namespace
 433          * @param ignoreDeleted if true, resources that have been moved to the trash
 434          *                      will be ignored
 435          * @throws ObjectNotFoundException if the user or resource was not found, with
 436          *                      the exception message mentioning the precise problem
 437          * @return the resource found
 438          */
 439         public Object getResourceAtPath(Long ownerId, String path, boolean ignoreDeleted)
 440                         throws ObjectNotFoundException;
 441
 442         /**
 443          * Copy the provided file to the specified destination.
 444          *
 445          * @param userId the ID of the current user
 446          * @param fileId the IF of the provided file
 447          * @param dest the path of the new resource
 448          * @throws ObjectNotFoundException if the user, file or destination was not
 449          *                      found, with     the exception message mentioning the precise problem
 450          * @throws DuplicateNameException if the specified name already exists in
 451          *          the destination folder, as either a folder or file
 452          * @throws GSSIOException if there was an error while accessing the file contents
 453          * @throws InsufficientPermissionsException
 454          * @throws QuotaExceededException
 455          */
 456         public void copyFile(Long userId, Long fileId, String dest) throws ObjectNotFoundException,
 457                         DuplicateNameException, GSSIOException, InsufficientPermissionsException, QuotaExceededException;
 458
 459         /**
 460          * Copy the provided file to the specified destination.
 461          *
 462          * @param userId the ID of the current user
 463          * @param ownerId the ID of the owner of the destination namespace
 464          * @param fileId the IF of the provided file
 465          * @param dest the path of the new resource
 466          * @throws ObjectNotFoundException if the user, file or destination was not
 467          *                      found, with     the exception message mentioning the precise problem
 468          * @throws DuplicateNameException if the specified name already exists in
 469          *          the destination folder, as either a folder or file
 470          * @throws GSSIOException if there was an error while accessing the file contents
 471          * @throws InsufficientPermissionsException
 472          * @throws QuotaExceededException
 473          */
 474         public void copyFileToPath(Long userId, Long ownerId, Long fileId, String dest) throws ObjectNotFoundException,
 475                         DuplicateNameException, GSSIOException, InsufficientPermissionsException, QuotaExceededException;
 476
 477         /**
 478          * Copy the provided file to the specified destination.
 479          *
 480          * @param userId the ID of the current user
 481          * @param fileIds the IDs of the provided files
 482          * @param destId the ID of the destination folder
 483          * @throws ObjectNotFoundException if the user, file or destination was not
 484          *                      found, with     the exception message mentioning the precise problem
 485          * @throws GSSIOException if there was an error while accessing the file contents
 486          * @throws DuplicateNameException if the specified name already exists in
 487          *          the destination folder, as either a folder or file
 488          * @throws InsufficientPermissionsException
 489          * @throws QuotaExceededException
 490          */
 491         public void copyFiles(Long userId, List<Long> fileIds, Long destId)
 492                         throws ObjectNotFoundException, DuplicateNameException, GSSIOException,
 493                         InsufficientPermissionsException, QuotaExceededException;
 494
 495         /**
 496          * Copy the provided file to the specified destination.
 497          *
 498          * @param userId the ID of the current user
 499          * @param fileId the IF of the provided file
 500          * @param destId the ID of the destination folder
 501          * @param destName the name of the new file
 502          * @throws ObjectNotFoundException if the user, file or destination was not
 503          *                      found, with     the exception message mentioning the precise problem
 504          * @throws GSSIOException if there was an error while accessing the file contents
 505          * @throws DuplicateNameException if the specified name already exists in
 506          *          the destination folder, as either a folder or file
 507          * @throws InsufficientPermissionsException
 508          * @throws QuotaExceededException
 509          */
 510         public void copyFile(Long userId, Long fileId, Long destId, String destName)
 511                         throws ObjectNotFoundException, DuplicateNameException, GSSIOException,
 512                         InsufficientPermissionsException, QuotaExceededException;
 513
 514         /**
 515          * Copy the provided folder to the specified destination.
 516          *
 517          * @param userId the ID of the current user
 518          * @param folderId the IF of the provided folder
 519          * @param dest the path of the new folder
 520          * @throws ObjectNotFoundException if the user, folder or destination was not
 521          *                      found, with     the exception message mentioning the precise problem
 522          * @throws DuplicateNameException if the specified name already exists in
 523          *          the destination folder, as either a folder or file
 524          * @throws InsufficientPermissionsException InsufficientPermissionsException if the user does not have the
 525          *          appropriate privileges
 526          */
 527         public void copyFolder(Long userId, Long folderId, String dest) throws ObjectNotFoundException,
 528                         DuplicateNameException, InsufficientPermissionsException;
 529
 530         /**
 531          * Copy the provided folder to the specified destination.
 532          *
 533          * @param userId the ID of the current user
 534          * @param folderId the IF of the provided folder
 535          * @param destId the ID of the destination folder
 536          * @param destName the name of the new folder
 537          * @throws ObjectNotFoundException if the user, folder or destination was not
 538          *                      found, with     the exception message mentioning the precise problem
 539          * @throws DuplicateNameException if the specified name already exists in
 540          *          the destination folder, as either a folder or file
 541          * @throws InsufficientPermissionsException InsufficientPermissionsException
 542          *                      if the user does not have the appropriate privileges
 543          */
 544         public void copyFolder(Long userId, Long folderId, Long destId, String destName)
 545                         throws ObjectNotFoundException, DuplicateNameException, InsufficientPermissionsException;
 546
 547         /**
 548          * Copy the provided folder and all its subfolders and files to the specified destination.
 549          *
 550          * @param userId the ID of the current user
 551          * @param ownerId the ID of the owner of the destination namespace
 552          * @param folderId the IF of the provided folder
 553          * @param dest the path of the new folder
 554          * @throws ObjectNotFoundException if the user, folder or destination was not
 555          *                      found, with     the exception message mentioning the precise problem
 556          * @throws DuplicateNameException if the specified name already exists in
 557          *          the destination folder, as either a folder or file
 558          * @throws InsufficientPermissionsException InsufficientPermissionsException if the user does not have the
 559          *          appropriate privileges
 560          * @throws QuotaExceededException if the user quota limit would be exceeded
 561          * @throws GSSIOException if there was an error while accessing the file contents
 562          */
 563         public void copyFolderStructureToPath(Long userId, Long ownerId, Long folderId, String dest) throws ObjectNotFoundException,
 564                         DuplicateNameException, InsufficientPermissionsException, GSSIOException, QuotaExceededException;
 565
 566         /**
 567          * Copy the provided folder and all its subfolders and files to the specified destination.
 568          *
 569          * @param userId the ID of the current user
 570          * @param folderId the IF of the provided folder
 571          * @param destId the ID of the destination folder
 572          * @param destName the name of the new folder
 573          * @throws ObjectNotFoundException if the user, folder or destination was not
 574          *                      found, with     the exception message mentioning the precise problem
 575          * @throws DuplicateNameException if the specified name already exists in
 576          *          the destination folder, as either a folder or file
 577          * @throws InsufficientPermissionsException InsufficientPermissionsException
 578          *                      if the user does not have the appropriate privileges
 579          * @throws GSSIOException if there was an error while accessing the file contents
 580          * @throws QuotaExceededException if the user quota limit would be exceeded
 581          */
 582         public void copyFolderStructure(Long userId, Long folderId, Long destId, String destName)
 583                         throws ObjectNotFoundException, DuplicateNameException, InsufficientPermissionsException,
 584                         GSSIOException, QuotaExceededException;
 585
 586         /**
 587          * Marks  the specified file as deleted in the specified user's namespace.
 588          *
 589          * @param userId the ID of the current user
 590          * @param fileId the ID of the file to delete
 591          * @throws ObjectNotFoundException if the user or file was not found, with
 592          *             the exception message mentioning the precise problem
 593          * @throws InsufficientPermissionsException if the user does not have the
 594          *             appropriate privileges
 595          */
 596         public void moveFileToTrash(Long userId, Long fileId) throws ObjectNotFoundException,
 597                         InsufficientPermissionsException;
 598
 599         /**
 600          * Marks  the specified deleted file as undeleted in the specified user's namespace.
 601          *
 602          * @param userId the ID of the current user
 603          * @param fileId the ID of the file to undelete
 604          * @throws ObjectNotFoundException if the user or file was not found, with
 605          *             the exception message mentioning the precise problem
 606          * @throws InsufficientPermissionsException if the user does not have the
 607          *             appropriate privileges
 608          *
 609          */
 610         public void removeFileFromTrash(Long userId, Long fileId) throws ObjectNotFoundException, InsufficientPermissionsException;
 611
 612         /**
 613          * Marks  the specified folder as deleted in the specified user's namespace.
 614          *
 615          * @param userId the ID of the current user
 616          * @param folderId the ID of the folder to delete
 617          * @throws ObjectNotFoundException if the user or file was not found, with
 618          *             the exception message mentioning the precise problem
 619          * @throws InsufficientPermissionsException if the user does not have the
 620          *             appropriate privileges
 621          */
 622         public void moveFolderToTrash(Long userId, Long folderId)
 623                         throws ObjectNotFoundException, InsufficientPermissionsException;
 624
 625         /**
 626          * Marks  the specified deleted folder as undeleted in the specified user's namespace.
 627          *
 628          * @param userId the ID of the current user
 629          * @param folderId the ID of the folder to undelete
 630          * @throws ObjectNotFoundException if the user or file was not found, with
 631          *             the exception message mentioning the precise problem
 632          * @throws InsufficientPermissionsException if the user does not have the
 633          *          appropriate privileges
 634          *
 635          */
 636         public void removeFolderFromTrash(Long userId, Long folderId) throws ObjectNotFoundException, InsufficientPermissionsException;
 637
 638         /**
 639          * Move the provided folder and all its subfolders and files to the specified destination.
 640          *
 641          * @param userId the ID of the current user
 642          * @param folderId the IF of the provided folder
 643          * @param destId the ID of the destination folder
 644          * @param destName the name of the new folder
 645          * @throws ObjectNotFoundException if the user, folder or destination was not
 646          *                      found, with     the exception message mentioning the precise problem
 647          * @throws DuplicateNameException if the specified name already exists in
 648          *          the destination folder, as either a folder or file
 649          * @throws InsufficientPermissionsException if the user does not have the
 650          *          appropriate privileges
 651          * @throws GSSIOException
 652          * @throws QuotaExceededException
 653          */
 654         public void moveFolder(Long userId, Long folderId, Long destId, String destName)
 655                         throws ObjectNotFoundException, DuplicateNameException, InsufficientPermissionsException,
 656                         GSSIOException, QuotaExceededException;
 657
 658         /**
 659          * Move the provided folder and all its subfolders and files to the specified destination.
 660          *
 661          * @param userId the ID of the current user
 662          * @param ownerId the owner of the destination namespace
 663          * @param folderId the IF of the provided folder
 664          * @param dest the path of the new folder
 665          * @throws ObjectNotFoundException if the user, folder or destination was not
 666          *                      found, with     the exception message mentioning the precise problem
 667          * @throws DuplicateNameException if the specified name already exists in
 668          *          the destination folder, as either a folder or file
 669          * @throws InsufficientPermissionsException InsufficientPermissionsException if the user does not have the
 670          *          appropriate privileges
 671          * @throws GSSIOException
 672          * @throws QuotaExceededException
 673          */
 674         public void moveFolderToPath(Long userId, Long ownerId, Long folderId, String dest) throws ObjectNotFoundException,
 675                         DuplicateNameException, InsufficientPermissionsException, GSSIOException, QuotaExceededException;
 676
 677         /**
 678          * Move the provided file to the specified destination.
 679          *
 680          * @param userId the ID of the current user
 681          * @param fileId the IF of the provided file
 682          * @param destId the ID of the destination folder
 683          * @param destName the name of the new file
 684          * @throws InsufficientPermissionsException
 685          * @throws ObjectNotFoundException if the user, file or destination was not
 686          *                      found, with     the exception message mentioning the precise problem
 687          * @throws GSSIOException if there was an error while accessing the file contents
 688          * @throws DuplicateNameException if the specified name already exists in
 689          *          the destination folder, as either a folder or file
 690          * @throws QuotaExceededException
 691          */
 692         public void moveFile(Long userId, Long fileId, Long destId, String destName)
 693                         throws InsufficientPermissionsException, ObjectNotFoundException,
 694                         DuplicateNameException, GSSIOException, QuotaExceededException;
 695
 696         /**
 697          * Move the provided file to the specified destination.
 698          *
 699          * @param userId the ID of the current user
 700          * @param ownerId the owner of the destination namespace
 701          * @param fileId the IF of the provided file
 702          * @param dest the path of the new file
 703          * @throws InsufficientPermissionsException
 704          * @throws ObjectNotFoundException if the user, file or destination was not
 705          *                      found, with     the exception message mentioning the precise problem
 706          * @throws GSSIOException if there was an error while accessing the file contents
 707          * @throws DuplicateNameException if the specified name already exists in
 708          *          the destination folder, as either a folder or file
 709          * @throws QuotaExceededException
 710          */
 711         public void moveFileToPath(Long userId, Long ownerId, Long fileId, String dest) throws ObjectNotFoundException, InsufficientPermissionsException, DuplicateNameException, GSSIOException, QuotaExceededException;
 712
 713         /**
 714          * move the provided file to the specified destination.
 715          *
 716          * @param userId the ID of the current user
 717          * @param fileIds the IDs of the provided files
 718          * @param destId the ID of the destination folder
 719          * @throws InsufficientPermissionsException
 720          * @throws ObjectNotFoundException if the user, file or destination was not
 721          *                      found, with     the exception message mentioning the precise problem
 722          * @throws GSSIOException if there was an error while accessing the file contents
 723          * @throws DuplicateNameException if the specified name already exists in
 724          *          the destination folder, as either a folder or file
 725          * @throws QuotaExceededException
 726          */
 727         public void moveFiles(Long userId, List<Long> fileIds, Long destId)
 728                         throws InsufficientPermissionsException, ObjectNotFoundException,
 729                         DuplicateNameException, GSSIOException, QuotaExceededException;
 730
 731         /**
 732          * Returns a list of All deleted files of a user.
 733          *
 734          * @param userId the ID of the User
 735          *       * @return the list of deleted file header objects
 736          * @throws ObjectNotFoundException if the user cannot be found
 737          */
 738         public List<FileHeader> getDeletedFiles(Long userId) throws ObjectNotFoundException;
 739
 740         /**
 741          * Returns a list of All deleted root folders of a user.
 742          *
 743          * @param userId the ID of the User
 744          *       * @return the list of deleted file header objects
 745          * @throws ObjectNotFoundException if the user cannot be found
 746          */
 747         public List<Folder> getDeletedRootFolders(Long userId) throws ObjectNotFoundException;
 748
 749         /**
 750          * Empty Trash by deleting all marked as deleted files and folders
 751          * @param userId
 752          * @throws ObjectNotFoundException if something goes wrong in the delete process
 753          * @throws InsufficientPermissionsException if something goes wrong in the delete process
 754          */
 755         public void emptyTrash(Long userId) throws ObjectNotFoundException, InsufficientPermissionsException;
 756
 757         /**
 758          * Restores All Trashed Items by undeleting all marked as deleted files and folders
 759          * @param userId
 760          * @throws ObjectNotFoundException if something goes wrong in the delete process
 761          * @throws InsufficientPermissionsException
 762          */
 763         public void restoreTrash(Long userId) throws ObjectNotFoundException, InsufficientPermissionsException;
 764
 765         /**
 766          * Search the system for a user with the specified username.
 767          * If no such user is found, the method returns null.
 768          *
 769          * @param username the username to search for
 770          * @return the User object with the specified username
 771          */
 772         public User findUser(String username);
 773
 774         /**
 775          * Create a new user with the specified name, username and e-mail address.
 776          *
 777          * @param username the username of the new user
 778          * @param name the name of the new user
 779          * @param mail the e-mail of the new user
 780          * @param idp the IdP of the new user
 781          * @param idpid the IdP identifier of the new user
 782          * @return the newly-created User object
 783          * @throws DuplicateNameException if a user with the same username already exists
 784          * @throws ObjectNotFoundException if no username was provided
 785          */
 786         public User createUser(String username, String name, String mail, String idp, String idpid)
 787                         throws DuplicateNameException, ObjectNotFoundException;
 788
 789         /**
 790          * Updates the authentication token for the specified user.
 791          *
 792          * @param userId the ID of the user whose token should be updated
 793          * @return the updated user
 794          * @throws ObjectNotFoundException if the user could not be found
 795          */
 796         public User updateUserToken(Long userId) throws ObjectNotFoundException;
 797
 798         /**
 799          * Updates the policy acceptance flag for the specified user.
 800          *
 801          * @param userId the ID of the user whose flag should be updated
 802          * @param isAccepted the new value of the flag
 803          * @return the updated user
 804          * @throws ObjectNotFoundException if the user could not be found
 805          */
 806         public User updateUserPolicyAcceptance(Long userId, boolean isAccepted) throws ObjectNotFoundException;
 807
 808         /**
 809          * Invalidates the authentication token for the specified user.
 810          *
 811          * @param userId the ID of the user whose token should be updated
 812          * @throws ObjectNotFoundException if the user could not be found
 813          */
 814         public void invalidateUserToken(Long userId) throws ObjectNotFoundException;
 815
 816         /**
 817          * Retrieve folder user and group permissions
 818          *
 819          * @param userId the ID of the user whose token should be updated
 820          * @param folderId the ID of the folder
 821          * @return the Set of permissions from requested folder
 822          * @throws ObjectNotFoundException if the user or folder could not be found
 823          * @throws InsufficientPermissionsException
 824          */
 825         public Set<Permission> getFolderPermissions(Long userId, Long folderId)
 826                         throws ObjectNotFoundException, InsufficientPermissionsException;
 827
 828         /**
 829          * Retrieve file user and group permissions
 830          *
 831          * @param userId the ID of the user whose token should be updated
 832          * @param fileId the ID of the folder
 833          * @return the Set of permissions from requested folder
 834          * @throws ObjectNotFoundException if the user or folder could not be found
 835          * @throws InsufficientPermissionsException
 836          */
 837         public Set<Permission> getFilePermissions(Long userId, Long fileId)
 838                         throws ObjectNotFoundException, InsufficientPermissionsException;
 839
 840         /**
 841          * Returns a list of all shared root folders of a user.
 842          *
 843          * @param userId the ID of the User
 844          * @return the list of shared root folders
 845          * @throws ObjectNotFoundException if the user cannot be found
 846          */
 847         public List<Folder> getSharedRootFolders(Long userId) throws ObjectNotFoundException;
 848
 849         /**
 850          * Returns a list of all shared files of a user that are not
 851          * inside other shared folders.
 852          *
 853          * @param userId the ID of the User
 854          * @return the list of shared files
 855          * @throws ObjectNotFoundException if the user cannot be found
 856          */
 857         public List<FileHeader> getSharedFilesNotInSharedFolders(Long userId) throws ObjectNotFoundException;
 858
 859         /**
 860          * Returns a list of all shared files of a user.
 861          *
 862          * @param userId the ID of the User
 863          * @return the list of shared files
 864          * @throws ObjectNotFoundException if the user cannot be found
 865          */
 866         public List<FileHeader> getSharedFiles(Long userId) throws ObjectNotFoundException;
 867
 868         /**
 869          * Returns a list of all shared folders of a user.
 870          *
 871          * @param userId the ID of the User
 872          * @return the list of shared folders
 873          * @throws ObjectNotFoundException if the user cannot be found
 874          */
 875         public List<Folder> getSharedFolders(Long userId) throws ObjectNotFoundException;
 876
 877         /**
 878          * Returns a list of all shared root folders of a user that calling
 879          * user has at least read permissions.
 880          *
 881          * @param ownerId the ID of the User
 882          * @return the list of shared root folders
 883          * @param callingUserId
 884          *
 885          * @throws ObjectNotFoundException if the user cannot be found
 886          */
 887         public List<Folder> getSharedRootFolders(Long ownerId, Long callingUserId)
 888                         throws ObjectNotFoundException;
 889
 890         /**
 891          * Returns a list of all shared  files of a user that calling user has
 892          * at least read permissions..
 893          *
 894          * @param ownerId the ID of the User
 895          * @return the list of shared files
 896          * @param callingUserId
 897          * @throws ObjectNotFoundException if the user cannot be found
 898          */
 899         public List<FileHeader> getSharedFiles(Long ownerId, Long callingUserId)
 900                         throws ObjectNotFoundException;
 901
 902         /**
 903          * Remove a user member from a group
 904          *
 905          * @param userId the ID of the User owning the group
 906          * @param groupId the ID of the requested group
 907          * @param memberId the ID of the member to be removed
 908          *
 909          * @throws ObjectNotFoundException if the user or group was not found, with
 910          *             the exception message mentioning the precise problem
 911          * @throws InsufficientPermissionsException
 912          */
 913         public void removeMemberFromGroup(Long userId, Long groupId, Long memberId)
 914                         throws ObjectNotFoundException, InsufficientPermissionsException;
 915
 916         /**
 917          * Retrieves the list of users sharing files to user identified by user id
 918          * @param userId
 919          * @return the List of users sharing files to user
 920          * @throws ObjectNotFoundException
 921          */
 922         public List<User> getUsersSharingFoldersForUser(Long userId) throws ObjectNotFoundException;
 923
 924         /**
 925          * Search Files
 926          *
 927          * @param userId
 928          * @param query
 929          * @return list of files that match query
 930          * @throws ObjectNotFoundException if no user or query was specified
 931          */
 932         public List<FileHeader> searchFiles(Long userId, String query) throws ObjectNotFoundException;
 933
 934         /**
 935          * Creates a nonce for the specified user.
 936          *
 937          * @param userId the ID of the user
 938          * @return the new nonce
 939          * @throws ObjectNotFoundException if the user could not be found
 940          */
 941         public Nonce createNonce(Long userId) throws ObjectNotFoundException;
 942
 943         /**
 944          * Find the nonce object for the specified encoded nonce, that should be
 945          * associated with the specified user.
 946          *
 947          * @param nonce the issued nonce in Base64 encoding
 948          * @param userId the ID of the user for whom this nonce should have been issued
 949          * @return the retrieved nonce object
 950          * @throws ObjectNotFoundException if the nonce or user were not found
 951          */
 952         public Nonce getNonce(String nonce, Long userId) throws ObjectNotFoundException;
 953
 954         /**
 955          * Remove the specified nonce from the persistent store.
 956          *
 957          * @param id the ID of the nonce
 958          * @throws ObjectNotFoundException if the specified nonce could not be found
 959          */
 960         public void removeNonce(Long id) throws ObjectNotFoundException;
 961
 962         /**
 963          * Activate the supplied nonce for the specified user.
 964          *
 965          * @param userId the ID of the user
 966          * @param nonce the nonce to activate
 967          * @param nonceExpiryDate the expiry date of the nonce
 968          * @throws ObjectNotFoundException
 969          */
 970         public void activateUserNonce(Long userId, String nonce, Date nonceExpiryDate) throws ObjectNotFoundException;
 971
 972         /**
 973          * Retrieves user statistics.
 974          *
 975          * @param userId the ID of the user
 976          * @return the statistics
 977          * @throws ObjectNotFoundException
 978          *
 979          */
 980         public StatsDTO getUserStatistics(Long userId) throws ObjectNotFoundException;
 981
 982         /**
 983          * Restore the file contents to the specified version.
 984          *
 985          * @param userId the ID of the user
 986          * @param fileId the ID of the file
 987          * @param version the version number of the desired file contents
 988          * @throws ObjectNotFoundException if the user or file was not
 989          *                      found, with     the exception message mentioning the precise problem
 990          * @throws InsufficientPermissionsException if the user does not have the
 991          *          appropriate privileges
 992          * @throws QuotaExceededException if the user quota limit would be exceeded
 993          * @throws GSSIOException if there was an error while accessing the file contents
 994          */
 995         public void restoreVersion(Long userId, Long fileId, int version)
 996                         throws ObjectNotFoundException, InsufficientPermissionsException,  GSSIOException, QuotaExceededException;
 997
 998         /**
 999          * Removes all old file versions for specified file keeping only the current revision
1000          *
1001          * @param userId the ID of the user
1002          * @param fileId the ID of the file
1003          *
1004          * @throws ObjectNotFoundException
1005          * @throws InsufficientPermissionsException
1006          *
1007          */
1008         public void removeOldVersions(Long userId, Long fileId)
1009                         throws ObjectNotFoundException, InsufficientPermissionsException;
1010
1011         /**
1012          * It is used by the Solr mbean to rebuild the index.
1013          */
1014         public String rebuildSolrIndex();
1015
1016         /**
1017          * It is used by the Solr mbean to refresh the index. It does not delete anything just re-add everything in the index
1018          */
1019         public String refreshSolrIndex();
1020
1021         /**
1022          * Creates a new file with the specified owner, parent folder and name. The
1023          * new file has the same permissions as its parent folder. The file contents
1024          * are already uploaded outside of externalAPI and the uploaded file is used as a parameter.
1025          *
1026          * @param userId the ID of the current user
1027          * @param folderId the ID of the parent folder
1028          * @param name the name of the new file
1029          * @param mimeType the MIME type of the file
1030          * @param fileSize the uploaded file size
1031          * @param filePath the uploaded file full path
1032          * @return The FileHeader created
1033          * @throws DuplicateNameException if the specified name already exists in
1034          *             the parent folder, as either a folder or file
1035          * @throws ObjectNotFoundException if the user or parent folder was not
1036          *             found, with the exception message mentioning the precise
1037          *             problem
1038          * @throws GSSIOException if there was an error while storing the file contents
1039          * @throws InsufficientPermissionsException
1040          * @throws QuotaExceededException
1041          */
1042         public FileHeader createFile(Long userId, Long folderId, String name, String mimeType, long fileSize, String filePath)
1043                         throws DuplicateNameException, ObjectNotFoundException, GSSIOException,
1044                         InsufficientPermissionsException, QuotaExceededException;
1045
1046         /**
1047          * Create a new FileBody with the supplied uploaded file as contents and make it the current body
1048          * of the file.
1049          *
1050          * @param userId the ID of the current user
1051          * @param fileId the ID of the file header object
1052          * @param mimeType the content type of the file
1053          * @param fileSize the uploaded file size
1054          * @param filePath the uploaded file full path
1055          * @return The FileHeader updated
1056          * @throws ObjectNotFoundException if the user or file was not found, with
1057          *                      the exception message mentioning the precise problem
1058          * @throws GSSIOException when an IO exception occurs
1059          * @throws InsufficientPermissionsException
1060          * @throws QuotaExceededException
1061          */
1062         public FileHeader updateFileContents(Long userId, Long fileId, String mimeType,
1063                                 long fileSize, String filePath) throws ObjectNotFoundException, GSSIOException,
1064                                 InsufficientPermissionsException, QuotaExceededException;
1065
1066         /**
1067          * Create a file based on inputstream without using transaction.
1068          *
1069          * @param stream
1070          * @param userId
1071          * @return the file
1072          * @throws IOException
1073          * @throws ObjectNotFoundException
1074          */
1075         @TransactionAttribute(TransactionAttributeType.NOT_SUPPORTED)
1076         public File uploadFile(InputStream stream, Long userId)
1077                         throws IOException, ObjectNotFoundException;
1078
1079         public void createFileUploadProgress(Long userId, String filename,
1080                                 Long bytesTransfered, Long fileSize) throws ObjectNotFoundException;
1081
1082         public FileUploadStatus getFileUploadStatus(Long userId, String fileName);
1083
1084         public void removeFileUploadProgress(Long userId, String filename)
1085                         throws ObjectNotFoundException;
1086
1087         /**
1088          * Fetch the file body with the specified version number.
1089          *
1090          * @param userId the ID of the current user
1091          * @param fileId the ID of the file header
1092          * @param version the version number
1093          * @return the file body
1094          * @throws ObjectNotFoundException if the user file or version
1095          *                      were not found
1096          * @throws InsufficientPermissionsException if the user does not
1097          *                      have enough privileges for reading this file
1098          */
1099         public FileBody getFileVersion(Long userId, Long fileId, int version) throws ObjectNotFoundException, InsufficientPermissionsException;
1100
1101         /**
1102          * Search the system for a user with the specified email address.
1103          * If no such user is found, the method returns null.
1104          */
1105         public User findUserByEmail(String email);
1106
1107         /**
1108          * Update the user with the values from the supplied object.
1109          */
1110         public void updateUser(User user);
1111
1112         /**
1113          * Update accounting information for given user.
1114          *
1115          * @param user The user to update
1116          * @param date Date of transaction
1117          * @param bandwidthDiff Bandwidth used; positive for addition,
1118          * negative for subtraction (e.g. to rollback)
1119          */
1120         public void updateAccounting(User user, Date date, long bandwidthDiff);
1121
1122         /**
1123          * Check if the user with the specified ID has permission to read the
1124          * folder with the supplied ID.
1125          */
1126         public boolean canReadFolder(Long userId, Long folderId) throws ObjectNotFoundException;
1127
1128         /**
1129          * Reset WebDAV password for given user.
1130          *
1131          * @param userId
1132          * @return the new password
1133          * @throws ObjectNotFoundException
1134          */
1135         public String resetWebDAVPassword(Long userId) throws ObjectNotFoundException;
1136
1137         /**
1138          * Find the invite for the specified invitation code.
1139          *
1140          * @param code the invitation code
1141          * @return the Invitation or null if not found
1142          */
1143         public Invitation findInvite(String code);
1144
1145         /**
1146          * Create a new user in the connected IdP.
1147          *
1148          * @param username the username of the new user
1149          * @param firstname the first name of the new user
1150          * @param lastname the last name of the new user
1151          * @param email the e-mail of the new user
1152          * @param password the password of the new user
1153          */
1154         public void createLdapUser(String username, String firstname, String lastname, String email, String password);
1155
1156         /**
1157          * Retrieves the available user classes.
1158          */
1159         public List<UserClass> getUserClasses();
1160
1161         /**
1162          * Upgrades the user class to the default "coupon bearer" class and marks
1163          * the provided coupon as used.
1164          *
1165          * @param username the username of the user
1166          * @param code the coupon code
1167          * @return the new user class
1168          * @throws InvitationUsedException when trying to reuse an already used invitation
1169          * @throws ObjectNotFoundException if the user was not found
1170          */
1171         public UserClass upgradeUserClass(String username, String code)
1172                         throws ObjectNotFoundException, InvitationUsedException;
1173
1174         /**
1175          * Retrieve the user class for coupon-bearing users.
1176          */
1177         public UserClass getCouponUserClass();
1178
1179         /**
1180          * Delete the actual file in the specified file system path.
1181          */
1182         public void deleteActualFile(String path);
1183
1184         /**
1185          * Update the userLogin with the values from the supplied object.
1186          */
1187         public void addUserLogin(UserLogin userLogin);
1188
1189         /**
1190          * Retrieves the user's current session login and the user's last login
1191          * @param userId
1192          * @return a list of last two user logins
1193          * @throws ObjectNotFoundException
1194          */
1195         public List<UserLogin> getLastUserLogins(Long userId) throws ObjectNotFoundException;
1196
1197         /**
1198          * Posts the file specified by id to solr indexing server
1199          *
1200      * @param solr
1201          * @param id
1202          */
1203         public void postFileToSolr(CommonsHttpSolrServer solr, Long id);
1204
1205         /**
1206          * @param folder
1207          * @throws ObjectNotFoundException
1208          */
1209         public Folder expandFolder(Folder folder) throws ObjectNotFoundException;
1210
1211         /**
1212          * @param folder
1213          * @return
1214          * @throws ObjectNotFoundException
1215          */
1216         FileHeader expandFile(FileHeader folder) throws ObjectNotFoundException;
1217
1218         /**
1219          * @param folder
1220          * @return
1221          * @throws ObjectNotFoundException
1222          */
1223         Group expandGroup(Group folder) throws ObjectNotFoundException;
1224 }