code.grnet.gr Git - pithos/blob - gss/src/gr/ebs/gss/server/soap/WSAPIRemote.java

   1 /*
   2  * Copyright 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.soap;
  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.dto.FileHeaderDTO;
  27 import gr.ebs.gss.server.domain.dto.FolderDTO;
  28 import gr.ebs.gss.server.domain.dto.GroupDTO;
  29 import gr.ebs.gss.server.domain.dto.PermissionDTO;
  30 import gr.ebs.gss.server.domain.dto.UserDTO;
  31
  32 import java.util.List;
  33 import java.util.Set;
  34
  35 import javax.activation.DataHandler;
  36 import javax.ejb.Remote;
  37
  38
  39 /**
  40  * @author kman
  41  *
  42  */
  43 @Remote
  44 public interface WSAPIRemote {
  45
  46         /* USER METHODS */
  47
  48         /**
  49          * Search the system for a user with the specified username.
  50          * If no such user is found, the method returns null.
  51          *
  52          * @param username the username to search for
  53          * @return the User object with the specified username
  54          */
  55         public UserDTO getUser(String username);
  56
  57         /**
  58          * Returns the group with the specified ID.
  59          *
  60          * @param groupId The ID of the Group to be found
  61          * @return The Group object
  62          * @throws ObjectNotFoundException if the group cannot be found
  63          */
  64         public GroupDTO getGroup(Long groupId) throws ObjectNotFoundException;
  65
  66         /**
  67          * Retrieve the list of groups for a particular user.
  68          *
  69          * @param userId the ID of the User
  70          * @return a List of Groups that belong to the specified User
  71          * @throws ObjectNotFoundException if the user was not found
  72          */
  73         public GroupDTO[] getGroups(Long userId) throws ObjectNotFoundException;
  74
  75         /**
  76          * Returns a list of users for the specified group
  77          *
  78          * @param userId the ID of the User
  79          * @param groupId the ID of the requested group
  80          * @return List<UserDTO>
  81          * @throws ObjectNotFoundException if the user or group was not found, with
  82          *             the exception message mentioning the precise problem
  83          */
  84         public UserDTO[] getUsers(Long userId, Long groupId) throws ObjectNotFoundException;
  85
  86         /**
  87          * Creates a new group with the specified owner and name.
  88          *
  89          * @param userId the ID of the current user
  90          * @param name the name of the new group
  91          * @throws DuplicateNameException if the new group name already exists
  92          * @throws ObjectNotFoundException if the user or group was not found, with
  93          *             the exception message mentioning the precise problem
  94          */
  95         public void createGroup(Long userId, String name) throws ObjectNotFoundException, DuplicateNameException;
  96
  97         /**
  98          * Deletes the specified group in the specified user's namespace.
  99          *
 100          * @param userId the ID of the current user
 101          * @param groupId the ID of the group to delete
 102          * @throws ObjectNotFoundException if the user or group was not found, with
 103          *             the exception message mentioning the precise problem
 104          * @throws InsufficientPermissionsException
 105          */
 106         public void deleteGroup(Long userId, Long groupId) throws ObjectNotFoundException, InsufficientPermissionsException;
 107
 108         /**
 109          * Adds a user to the specified group
 110          *
 111          * @param userId the ID of the current user
 112          * @param groupId the id of the new group
 113          * @param userToAddId the id of the user to add
 114          * @throws DuplicateNameException if the user already exists in group
 115          * @throws ObjectNotFoundException if the user or group was not found, with
 116          *             the exception message mentioning the precise problem
 117          * @throws InsufficientPermissionsException
 118          */
 119         public void addUserToGroup(Long userId, Long groupId, Long userToAddId) throws ObjectNotFoundException, DuplicateNameException, InsufficientPermissionsException;
 120
 121         /**
 122          * Remove a user member from a group
 123          *
 124          * @param userId the ID of the User owning the group
 125          * @param groupId the ID of the requested group
 126          * @param memberId the ID of the member to be removed
 127          *
 128          * @throws ObjectNotFoundException if the user or group was not found, with
 129          *             the exception message mentioning the precise problem
 130          * @throws InsufficientPermissionsException
 131          */
 132         public void removeMemberFromGroup(Long userId, Long groupId, Long memberId) throws ObjectNotFoundException, InsufficientPermissionsException;
 133
 134
 135         /* FOLDER METHODS */
 136         /**
 137          * Retrieves the root folder for the specified user. The caller must ensure
 138          * that the userId exists.
 139          *
 140          * @param userId
 141          * @return Folder
 142          * @throws ObjectNotFoundException if no Folder or user was found
 143          */
 144         public FolderDTO getRootFolder(Long userId) throws ObjectNotFoundException;
 145
 146         /**
 147          * Retrieve the folder with the specified ID.
 148          *
 149          * @param userId the ID of the current user
 150          * @param folderId the ID of the folder to retrieve
 151          * @return the folder found
 152          * @throws ObjectNotFoundException if the folder or the user was not found
 153          * @throws InsufficientPermissionsException
 154          */
 155         public FolderDTO getFolder(Long userId, Long folderId) throws ObjectNotFoundException, InsufficientPermissionsException;
 156
 157         /**
 158          * Creates a new folder with the specified owner, parent folder and name.
 159          * New folder has the same permissions as its parent
 160          *
 161          * @param userId
 162          * @param parentId
 163          * @param name
 164          * @throws DuplicateNameException if the specified name already exists in
 165          *             the parent folder, as either a folder or file
 166          * @throws ObjectNotFoundException if the user or parent folder was not
 167          *             found, with the exception message mentioning the precise
 168          *             problem
 169          * @throws InsufficientPermissionsException
 170          */
 171         public void createFolder(Long userId, Long parentId, String name) throws DuplicateNameException, ObjectNotFoundException, InsufficientPermissionsException;
 172
 173         /**
 174          * Deletes the specified folder if the specified user has the appropriate
 175          * permission
 176          *
 177          * @param userId
 178          * @param folderId
 179          * @throws InsufficientPermissionsException if the user does not have the
 180          *             appropriate privileges
 181          * @throws ObjectNotFoundException if the user or folder was not found, with
 182          *             the exception message mentioning the precise problem
 183          */
 184         public void deleteFolder(Long userId, Long folderId) throws InsufficientPermissionsException, ObjectNotFoundException;
 185
 186         /**
 187          * Retrieve the subfolders of the specified folder.
 188          *
 189          * @param userId the ID of the current user
 190          * @param folderId the ID of the folder to retrieve
 191          * @return the list of subfolders found
 192          * @throws ObjectNotFoundException if the folder or user was not found
 193          * @throws InsufficientPermissionsException
 194          */
 195         public FolderDTO[] getSubfolders(Long userId, Long folderId) throws ObjectNotFoundException, InsufficientPermissionsException;
 196
 197         /**
 198          * Modifies the specified folder if the specified user has the appropriate
 199          * permission.
 200          *
 201          * @param userId the ID of the current user
 202          * @param folderId the ID of the folder to retrieve
 203          * @param folderName
 204          * @throws InsufficientPermissionsException if the user does not have the
 205          *             appropriate privileges
 206          * @throws ObjectNotFoundException if the user or folder was not found, with
 207          *             the exception message mentioning the precise problem
 208          * @throws DuplicateNameException if the specified name already exists in
 209          *             the parent folder, as either a folder or file
 210          */
 211         public void modifyFolder(Long userId, Long folderId, String folderName) throws InsufficientPermissionsException, ObjectNotFoundException, DuplicateNameException;
 212
 213         /**
 214          * Copy the provided folder to the specified destination.
 215          *
 216          * @param userId the ID of the current user
 217          * @param folderId the IF of the provided folder
 218          * @param destId the ID of the destination folder
 219          * @param destName the name of the new folder
 220          * @throws ObjectNotFoundException if the user, folder or destination was not
 221          *                      found, with     the exception message mentioning the precise problem
 222          * @throws DuplicateNameException if the specified name already exists in
 223          *          the destination folder, as either a folder or file
 224          * @throws InsufficientPermissionsException InsufficientPermissionsException if the user does not have the
 225          *          appropriate privileges
 226          * @throws GSSIOException
 227          * @throws QuotaExceededException
 228          */
 229         public void copyFolder(Long userId, Long folderId, Long destId, String destName) throws ObjectNotFoundException, DuplicateNameException, InsufficientPermissionsException, GSSIOException, QuotaExceededException;
 230
 231
 232
 233         /**
 234          * Move the provided folder and all its subfolders and files to the specified destination.
 235          *
 236          * @param userId the ID of the current user
 237          * @param folderId the IF of the provided folder
 238          * @param destId the ID of the destination folder
 239          * @param destName the name of the new folder
 240          * @throws ObjectNotFoundException if the user, folder or destination was not
 241          *                      found, with     the exception message mentioning the precise problem
 242          * @throws DuplicateNameException if the specified name already exists in
 243          *          the destination folder, as either a folder or file
 244          * @throws InsufficientPermissionsException InsufficientPermissionsException if the user does not have the
 245          *          appropriate privileges
 246          * @throws GSSIOException
 247          * @throws QuotaExceededException
 248          */
 249         public void moveFolder(Long userId, Long folderId, Long destId, String destName) throws ObjectNotFoundException, DuplicateNameException, InsufficientPermissionsException, GSSIOException, QuotaExceededException;
 250
 251
 252         /**
 253          * Retrieve folder user and group permissions
 254          *
 255          * @param userId the ID of the user whose token should be updated
 256          * @param folderId the ID of the folder
 257          * @return the Set of permissions from requested folder
 258          * @throws ObjectNotFoundException if the user or folder could not be found
 259          * @throws InsufficientPermissionsException
 260          */
 261         public Set<PermissionDTO> getFolderPermissions(Long userId, Long folderId) throws ObjectNotFoundException, InsufficientPermissionsException;
 262
 263
 264         /**
 265          * update folder permissions
 266          * @param userId
 267          * @param folderId
 268          * @param permissions
 269          * @throws ObjectNotFoundException
 270          * @throws InsufficientPermissionsException
 271          */
 272         public void setFolderPermissions(Long userId, Long folderId, Set<PermissionDTO> permissions) throws ObjectNotFoundException, InsufficientPermissionsException;
 273
 274         /**
 275          * Returns a list of all deleted root folders of a user.
 276          *
 277          * @param userId the ID of the User
 278          * @return the list of deleted file header objects
 279          * @throws ObjectNotFoundException if the user cannot be found
 280          */
 281         public FolderDTO[] getDeletedRootFolders(Long userId) throws ObjectNotFoundException;
 282
 283
 284         /* FILE METHODS */
 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          * @throws DuplicateNameException if the specified name already exists in
 296          *             the parent folder, as either a folder or file
 297          * @throws ObjectNotFoundException if the user or parent folder was not
 298          *             found, with the exception message mentioning the precise
 299          *             problem
 300          * @throws GSSIOException if there was an error while storing the file contents
 301          * @throws InsufficientPermissionsException
 302          * @throws QuotaExceededException
 303          */
 304         public void createFile(Long userId, Long folderId, String name, String mimeType, DataHandler stream) throws DuplicateNameException, ObjectNotFoundException, GSSIOException, InsufficientPermissionsException, QuotaExceededException;
 305
 306         /**
 307          * Deletes the specified file in the specified user's namespace.
 308          *
 309          * @param userId the ID of the current user
 310          * @param fileId the ID of the file to delete
 311          * @throws ObjectNotFoundException if the user or file was not found, with
 312          *             the exception message mentioning the precise problem
 313          * @throws InsufficientPermissionsException if the user does not have the
 314          *             appropriate privileges
 315          */
 316         public void deleteFile(Long userId, Long fileId) throws ObjectNotFoundException, InsufficientPermissionsException;
 317
 318         /**
 319          * Creates a new tag for the specified user and file.
 320          *
 321          * @param userId the creator of the tag
 322          * @param fileHeaderId the file that is tagged
 323          * @param tag the tag
 324          * @throws ObjectNotFoundException if the user or the file was not found
 325          */
 326         public void createTag(Long userId, Long fileHeaderId, String tag) throws ObjectNotFoundException;
 327
 328         /**
 329          * Returns all tags defined by the specified user
 330          *
 331          * @param userId
 332          * @return Set<String>
 333          * @throws ObjectNotFoundException if the user was null
 334          */
 335         public String[] getUserTags(final Long userId) throws ObjectNotFoundException;
 336
 337         /**
 338          * Updates name and tags for the specified file
 339          *
 340          * @param userId
 341          * @param fileId
 342          * @param name
 343          * @param tagSet a String that contains tags separated by comma
 344          * @throws ObjectNotFoundException
 345          * @throws InsufficientPermissionsException
 346          */
 347         public void updateFile(Long userId, Long fileId, String name, String tagSet) throws ObjectNotFoundException, InsufficientPermissionsException;
 348
 349         /**
 350          * Retrieve the contents of the current body for the file
 351          * with the specified FileHeader ID. The file contents
 352          * are provided as an InputStream from which the caller can
 353          * retrieve the raw bytes.
 354          *
 355          * @param userId the ID of the current user
 356          * @param fileId the ID of the file to retrieve
 357          * @return an InputStream from the current file body contents
 358          * @throws ObjectNotFoundException if the file or the user was not found
 359          * @throws InsufficientPermissionsException  if the user does not have the
 360          *             appropriate privileges
 361          */
 362         public DataHandler getFileContents(Long userId, Long fileId) throws ObjectNotFoundException, InsufficientPermissionsException;
 363
 364         /**
 365          * Retrieve the file with the specified ID.
 366          *
 367          * @param userId the ID of the current user
 368          * @param fileId the ID of the file to retrieve
 369          * @return the file found
 370          * @throws ObjectNotFoundException if the file or the user was not found, with
 371          *                      the exception message mentioning the precise problem
 372          * @throws InsufficientPermissionsException
 373          */
 374         public FileHeaderDTO getFile(Long userId, Long fileId) throws ObjectNotFoundException, InsufficientPermissionsException;
 375
 376
 377
 378         /**
 379          * Create a new FileBody with the supplied contents and make it the current body
 380          * of the file.
 381          *
 382          * @param userId the ID of the current user
 383          * @param fileId the ID of the file header object
 384          * @param mimeType the content type of the file
 385          * @param resourceInputStream a stream of the file contents
 386          * @throws ObjectNotFoundException if the user or file was not found, with
 387          *                      the exception message mentioning the precise problem
 388          * @throws GSSIOException if there was an error while storing the file contents
 389          * @throws InsufficientPermissionsException
 390          * @throws QuotaExceededException
 391          */
 392         public void updateFileContents(Long userId, Long fileId, String mimeType, DataHandler resourceInputStream) throws ObjectNotFoundException, GSSIOException, InsufficientPermissionsException, QuotaExceededException;
 393
 394         /**
 395          * Copy the provided file to the specified destination.
 396          *
 397          * @param userId the ID of the current user
 398          * @param fileId the IF of the provided file
 399          * @param destId the ID of the destination folder
 400          * @param destName the name of the new file
 401          * @throws ObjectNotFoundException if the user, file or destination was not
 402          *                      found, with     the exception message mentioning the precise problem
 403          * @throws GSSIOException if there was an error while accessing the file contents
 404          * @throws DuplicateNameException if the specified name already exists in
 405          *          the destination folder, as either a folder or file
 406          * @throws InsufficientPermissionsException
 407          * @throws QuotaExceededException
 408          */
 409         public void copyFile(Long userId, Long fileId, Long destId, String destName) throws ObjectNotFoundException, DuplicateNameException, GSSIOException, InsufficientPermissionsException, QuotaExceededException;
 410
 411
 412         /**
 413          * move the provided file to the specified destination.
 414          *
 415          * @param userId the ID of the current user
 416          * @param fileId the IF of the provided file
 417          * @param destId the ID of the destination folder
 418          * @param destName the name of the new file
 419          * @throws InsufficientPermissionsException
 420          * @throws ObjectNotFoundException if the user, file or destination was not
 421          *                      found, with     the exception message mentioning the precise problem
 422          * @throws GSSIOException if there was an error while accessing the file contents
 423          * @throws DuplicateNameException if the specified name already exists in
 424          *          the destination folder, as either a folder or file
 425          * @throws QuotaExceededException
 426          */
 427         public void moveFile(Long userId, Long fileId, Long destId, String destName) throws InsufficientPermissionsException, ObjectNotFoundException, DuplicateNameException, GSSIOException, QuotaExceededException;
 428
 429         /**
 430          * Returns a list of all deleted files of a user.
 431          *
 432          * @param userId the ID of the User
 433          * @return the list of deleted file header objects
 434          * @throws ObjectNotFoundException if the user cannot be found
 435          */
 436         public FileHeaderDTO[] getDeletedFiles(Long userId) throws ObjectNotFoundException;
 437
 438
 439
 440
 441         /**
 442          * Retrieve file user and group permissions
 443          *
 444          * @param userId the ID of the user whose token should be updated
 445          * @param fileId the ID of the folder
 446          * @return the Set of permissions from requested folder
 447          * @throws ObjectNotFoundException if the user or folder could not be found
 448          * @throws InsufficientPermissionsException
 449          */
 450         public Set<PermissionDTO> getFilePermissions(Long userId, Long fileId) throws ObjectNotFoundException, InsufficientPermissionsException;
 451
 452
 453         /**
 454          * update file permissions
 455          * @param userId
 456          * @param fileId
 457          * @param permissions
 458          * @throws ObjectNotFoundException
 459          * @throws InsufficientPermissionsException
 460          */
 461         public void setFilePermissions(Long userId, Long fileId, boolean readForAll, Set<PermissionDTO> permissions) throws ObjectNotFoundException, InsufficientPermissionsException;
 462
 463
 464
 465         /**
 466          * Returns a list of files contained in the folder specified by its id.
 467          *
 468          * @param userId the ID of the User
 469          * @param folderId the ID of the folder containing the files
 470          * @return the list of file header objects
 471          * @throws ObjectNotFoundException if the user or the folder cannot be found
 472          * @throws InsufficientPermissionsException
 473          */
 474         public FileHeaderDTO[] getFiles(Long userId, Long folderId) throws ObjectNotFoundException, InsufficientPermissionsException;
 475
 476         /* TRASH METHODS */
 477
 478         /**
 479          * Marks  the specified file as deleted in the specified user's namespace.
 480          *
 481          * @param userId the ID of the current user
 482          * @param fileId the ID of the file to delete
 483          * @throws ObjectNotFoundException if the user or file was not found, with
 484          *             the exception message mentioning the precise problem
 485          * @throws InsufficientPermissionsException if the user does not have the
 486          *             appropriate privileges
 487          */
 488         public void moveFileToTrash(Long userId, Long fileId) throws ObjectNotFoundException, InsufficientPermissionsException;
 489
 490         /**
 491          * Marks  the specified deleted file as undeleted in the specified user's namespace.
 492          *
 493          * @param userId the ID of the current user
 494          * @param fileId the ID of the file to undelete
 495          * @throws ObjectNotFoundException if the user or file was not found, with
 496          *             the exception message mentioning the precise problem
 497          * @throws InsufficientPermissionsException
 498          *
 499          */
 500         public void restoreFileFromTrash(Long userId, Long fileId) throws ObjectNotFoundException, InsufficientPermissionsException;
 501
 502         /**
 503          * Marks  the specified folder as deleted in the specified user's namespace.
 504          *
 505          * @param userId the ID of the current user
 506          * @param folderId the ID of the folder to delete
 507          * @throws ObjectNotFoundException if the user or file was not found, with
 508          *             the exception message mentioning the precise problem
 509          * @throws InsufficientPermissionsException if the user does not have the
 510          *             appropriate privileges
 511          */
 512         public void moveFolderToTrash(Long userId, Long folderId) throws ObjectNotFoundException, InsufficientPermissionsException;
 513
 514         /**
 515          * Marks  the specified deleted folder as undeleted in the specified user's namespace.
 516          *
 517          * @param userId the ID of the current user
 518          * @param folderId the ID of the folder to undelete
 519          * @throws ObjectNotFoundException if the user or file was not found, with
 520          *             the exception message mentioning the precise problem
 521          * @throws InsufficientPermissionsException
 522          *
 523          */
 524         public void restoreFolderFromTrash(Long userId, Long folderId) throws ObjectNotFoundException, InsufficientPermissionsException;
 525
 526         /**
 527          * Empty Trash by deleting all marked as deleted files and folders
 528          * @param userId
 529          * @throws ObjectNotFoundException if something goes wrong in the delete process
 530          * @throws InsufficientPermissionsException  if something goes wrong in the delete process
 531          */
 532         public void emptyTrash(Long userId) throws ObjectNotFoundException, InsufficientPermissionsException;
 533
 534         /*SHARING METHODS */
 535
 536         /**
 537          * Returns a list of All Shared root folders of a user.
 538          *
 539          * @param userId the ID of the User
 540          *       * @return the list of shared root folders
 541          * @throws ObjectNotFoundException if the user cannot be found
 542          */
 543         public List<FolderDTO> getSharedRootFolders(Long userId) throws ObjectNotFoundException;
 544
 545         /**
 546          * Returns a list of All Shared  files of a user.
 547          *
 548          * @param userId the ID of the User
 549          *       * @return the list of shared files
 550          * @throws ObjectNotFoundException if the user cannot be found
 551          */
 552         public List<FileHeaderDTO> getSharedFiles(Long userId) throws ObjectNotFoundException;
 553
 554         /**
 555          * Returns a list of All Shared root folders of a user that calling user has at least read permissions.
 556          *
 557          * @param ownerId the ID of the User
 558          * @return the list of shared root folders
 559          * @param callingUserId
 560          *
 561          * @throws ObjectNotFoundException if the user cannot be found
 562          */
 563         public List<FolderDTO> getSharedRootFoldersOfUser(Long ownerId, Long callingUserId) throws ObjectNotFoundException;
 564
 565         /**
 566          * Returns a list of All Shared  files of a user that calling user has at least read permissions..
 567          *
 568          * @param ownerId the ID of the User
 569          * @return the list of shared files
 570          * @param callingUserId
 571          * @throws ObjectNotFoundException if the user cannot be found
 572          */
 573         public List<FileHeaderDTO> getSharedFilesOfUser(Long ownerId, Long callingUserId) throws ObjectNotFoundException;
 574
 575
 576
 577         /**
 578          * Retrieves the list of users sharing files to user identified by user id
 579          * @param userId
 580          * @return the List of users sharing files to user
 581          * @throws ObjectNotFoundException
 582          */
 583         public List<UserDTO> getUsersSharingFoldersForUser(Long userId) throws ObjectNotFoundException;
 584
 585
 586         /**
 587          * Retrieve the subfolders of the specified folder that are shared to others.
 588          *
 589          * @param userId the ID of the current user
 590          * @param folderId the ID of the folder to retrieve
 591          * @return the list of subfolders found
 592          * @throws ObjectNotFoundException if the folder or user was not found
 593          */
 594         public List<FolderDTO> getSharedSubfolders(Long userId, Long folderId) throws ObjectNotFoundException;
 595
 596
 597
 598
 599
 600 }