Package com.spotfire.ws.pub

Interface LibraryService

  • public interface LibraryService
    A public SOAP web service for the TIBCO Spotfire Server Library.

    Authorization

    • All access to this service require an access token that is issued for the "api.soap.library-service" scope.
    • Some operations require an access token that is also issued for the "api.soap.impersonate" scope.
    • Apart from the impersonation operations, all operations evaluate the library permissions of the calling user (the OAuth 2.0 client principal), where applicable.

    Important things to note

    • All modifying operations are atomic unless stated otherwise.
    • An analysis file (.dxp) may be downloaded from http[s]://<host>[:<port>]/spotfire/library?guid=<id>.
    • An analysis file (.dxp) may be opened in TIBCO Spotfire Web Player from http[s]://<host>[:<port>]/spotfire/wp/OpenAnalysis?file=<id>.
    • Recent changes to the Library may also be viewed through an RSS feed: http[s]://<host>[:<port>]/spotfire/library?rss.
    Since:
    5.5

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String IMPERSONATION_SCOPE
      The OAuth 2.0 scope needed to access the operations in this service where another user is impersonated.
      static java.lang.String SERVICE_SCOPE
      The OAuth 2.0 scope needed to access any operation in this service.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void clearPermissions​(Guid itemId, boolean includeDescendants)
      Clears the permissions on the given library item (and possibly on all of its descendants) meaning that the item will inherit its permissions instead.
      java.util.List<java.lang.String> copyFolders​(java.util.List<java.lang.String> folders, java.lang.String destinationFolder, LibraryConflictResolution conflictResolution)
      Copies the given folders to the given destination folder.
      java.util.List<LibraryItem> copyItems​(java.util.List<Guid> itemIds, Guid destinationFolderId, LibraryConflictResolution conflictResolution)
      Copies the given items to the given destination folder.
      LibraryItem createFolder​(java.lang.String title, java.lang.String description, Guid parentId)
      Creates a new folder.
      java.util.List<LibraryItem> getChildItems​(Guid folderId)
      Returns all items (if any) within the given folder that the calling user has read access to.
      java.util.List<LibraryItem> getChildItemsAsUser​(Guid folderId, UserName userName)
      Returns all items (if any) within the given folder that the given user has read access to.
      java.util.List<LibraryItem> getItems​(java.util.List<Guid> itemIds)
      Returns the items with the given IDs that the calling user has read access to.
      java.util.List<LibraryItem> getItemsAsUser​(java.util.List<Guid> itemIds, UserName userName)
      Returns the items with the given IDs that the given user has read access to.
      java.util.List<java.lang.String> getItemTypes()
      Returns all item types.
      AclEntryCollection getPermissions​(Guid itemId)
      Returns the effective permissions of the given library item.
      LibraryItem getRootItem()
      Returns the root item.
      java.lang.String idToPath​(Guid itemId)
      Returns the path to the given library item.
      java.util.List<LibraryItem> moveItems​(java.util.List<Guid> itemIds, Guid destinationFolderId, LibraryConflictResolution conflictResolution)
      Moves the given items to the given destination folder.
      Guid pathToId​(java.lang.String path, java.lang.String type)
      Returns the ID of the item of the given type in the given location.
      void removeItems​(java.util.List<Guid> itemIds)
      Removes the given items.
      java.util.List<LibraryItem> searchItems​(java.lang.String searchExpression, Guid locationId, int maxResults)
      Returns all items, up to the given limit, in the given location that matches the given search expression.
      java.util.List<LibraryItem> searchItemsAsUser​(java.lang.String searchExpression, Guid locationId, int maxResults, UserName userName)
      Returns all items, up to the given limit, in the given location that matches the given search expression.
      void setDescription​(Guid itemId, java.lang.String description)
      Sets the description of the given library item.
      void setPermissions​(Guid itemId, AclEntryCollection aclEntryCollection)
      Sets the permissions on the given library item.
      void setProperties​(Guid itemId, java.util.Collection<LibraryProperty> properties)
      Sets the properties of the given library item.
      void setTitle​(Guid itemId, java.lang.String title)
      Sets the title of the given library item.

    • Method Detail

      • getChildItems

        java.util.List<LibraryItem> getChildItems​(Guid folderId)
                                   throws LibraryServiceException
        Returns all items (if any) within the given folder that the calling user has read access to.
        Parameters:
        folderId - the ID of the folder item to retrieve the child items of
        Returns:
        a (possibly empty) list of all child items of the given folder item
        Throws:
        LibraryServiceException - if the folder item does not exist or isn't a folder or if an unexpected error occurs

      • getChildItemsAsUser

        java.util.List<LibraryItem> getChildItemsAsUser​(Guid folderId,
                                                UserName userName)
                                         throws LibraryServiceException
        Returns all items (if any) within the given folder that the given user has read access to.

        Authorization
        Access to this operation requires an access token that is issued for the "api.soap.impersonate" scope, in addition to the "api.soap.library-service" scope.

        Parameters:
        folderId - the ID of the folder item to retrieve the child items of
        userName - the name of the user for which to retrieve the child items as
        Returns:
        a (possibly empty) list of all child items of the given folder item
        Throws:
        LibraryServiceException - if the folder item does not exist or isn't a folder or if an unexpected error occurs

      • getItems

        java.util.List<LibraryItem> getItems​(java.util.List<Guid> itemIds)
                              throws LibraryServiceException
        Returns the items with the given IDs that the calling user has read access to. Items that cannot be found are ignored.
        Parameters:
        itemIds - the IDs of the items to retrieve
        Returns:
        a list of the items with the given IDs
        Throws:
        LibraryServiceException - if an unexpected error occurs

      • getItemsAsUser

        java.util.List<LibraryItem> getItemsAsUser​(java.util.List<Guid> itemIds,
                                           UserName userName)
                                    throws LibraryServiceException
        Returns the items with the given IDs that the given user has read access to. Items that cannot be found are ignored.

        Authorization
        Access to this operation requires an access token that is issued for the "api.soap.impersonate" scope, in addition to the "api.soap.library-service" scope.

        Parameters:
        itemIds - the IDs of the items to retrieve
        userName - the name of the user to retrieve items for
        Returns:
        a list of the items with the given IDs
        Throws:
        LibraryServiceException - if an unexpected error occurs

      • searchItems

        java.util.List<LibraryItem> searchItems​(java.lang.String searchExpression,
                                        Guid locationId,
                                        int maxResults)
                                 throws LibraryServiceException
        Returns all items, up to the given limit, in the given location that matches the given search expression. Only items that the calling user has access to will be returned.
        Parameters:
        searchExpression - a library search expression
        locationId - the ID of a folder item in which to search (all subfolders will also be included) or null if the entire library should be searched
        maxResults - the maximum number of items to be returned or a number less than or equal to 0 if all matching items should be returned
        Returns:
        a (possibly) empty list of items in the given location matching the search expression
        Throws:
        LibraryServiceException - if an unexpected error occurs

      • searchItemsAsUser

        java.util.List<LibraryItem> searchItemsAsUser​(java.lang.String searchExpression,
                                              Guid locationId,
                                              int maxResults,
                                              UserName userName)
                                       throws LibraryServiceException
        Returns all items, up to the given limit, in the given location that matches the given search expression. Only items that the given user has access to will be returned.

        Authorization
        Access to this operation requires an access token that is issued for the "api.soap.impersonate" scope, in addition to the "api.soap.library-service" scope.

        Parameters:
        searchExpression - a library search expression
        locationId - the ID of a folder item in which to search (all subfolders will also be included) or null if the entire library should be searched
        maxResults - the maximum number of items to be returned or a number less than or equal to 0 if all matching items should be returned
        userName - the name of the user to search as
        Returns:
        a (possibly) empty list of items in the given location matching the search expression
        Throws:
        LibraryServiceException - if an unexpected error occurs

      • getItemTypes

        java.util.List<java.lang.String> getItemTypes()
                                       throws LibraryServiceException
        Returns all item types. Each library item has one, and only one, item type which together with its parent and title uniquely identifies the item.

        The current set of available types:

        • spotfire.folder - A folder
        • spotfire.dxp - A DXP file
        • spotfire.query - An information link
        • spotfire.filter - An Information Services filter
        • spotfire.join - An Information Services join
        • spotfire.datasource - An Information Services data source
        • spotfire.column - An Information Services column
        • spotfire.procedure - An Information Services procedure
        • spotfire.datafunction - A data function
        • spotfire.colorscheme - A color scheme
        • spotfire.dxpscript - A script
        Returns:
        all item types
        Throws:
        LibraryServiceException - if an unexpected error occurs

      • createFolder

        LibraryItem createFolder​(java.lang.String title,
                         java.lang.String description,
                         Guid parentId)
                  throws LibraryServiceException
        Creates a new folder.
        Parameters:
        title - the title of the new folder, must not be null or an empty string and must not exceed 256 characters, it also cannot contain any of the following characters: \ / : * ? " < > |
        description - a description of the folder, may be null but must not exceed 1000 characters
        parentId - the ID of the parent item, or null if the item should be created directly under the root
        Returns:
        the newly created item
        Throws:
        LibraryServiceException - if the title or the description is invalid, if the parent item doesn't exists, if a folder with the same name in the same location already exists, if the calling user doesn't have write access to the location or if an unexpected error occurs

      • setTitle

        void setTitle​(Guid itemId,
              java.lang.String title)
       throws LibraryServiceException
        Sets the title of the given library item.
        Parameters:
        itemId - the ID of the library item to set the title for, must not be null
        title - the new title, must not be null or an empty string and must not exceed 256 characters, it also cannot contain any of the following characters: \ / : * ? " < > |
        Throws:
        LibraryServiceException - if the library item doesn't exist, if the title is invalid, if the calling user doesn't have write access to the item or if an unexpected error occurs

      • setDescription

        void setDescription​(Guid itemId,
                    java.lang.String description)
             throws LibraryServiceException
        Sets the description of the given library item.
        Parameters:
        itemId - the ID of the library item to set the title for, must not be null
        description - the new description, must not exceed 1000 characters
        Throws:
        LibraryServiceException - if the library item doesn't exist, if the description is invalid, if the calling user doesn't have write access to the item or if an unexpected error occurs

      • setProperties

        void setProperties​(Guid itemId,
                   java.util.Collection<LibraryProperty> properties)
            throws LibraryServiceException
        Sets the properties of the given library item.
        Parameters:
        itemId - the ID of the library item to set the properties for, must not be null
        properties - the set of new properties, may be null or empty but each key must not be null or empty or exceed 150 characters, each value must not be null or empty
        Throws:
        LibraryServiceException - if the library item doesn't exist, if any property key exceeds 150 characters, if the calling user doesn't have write access to the item or if an unexpected error occurs

      • copyItems

        java.util.List<LibraryItem> copyItems​(java.util.List<Guid> itemIds,
                                      Guid destinationFolderId,
                                      LibraryConflictResolution conflictResolution)
                               throws LibraryServiceException
        Copies the given items to the given destination folder.
        Parameters:
        itemIds - the IDs of the library items to copy
        destinationFolderId - the ID of the destination folder, must not be null
        conflictResolution - the conflict resolution algorithm to use on any ID or path conflicts, must not be null
        Returns:
        the newly copied items
        Throws:
        LibraryServiceException - if the destination folder or any of the items to be copied doesn't exist, if the calling user doesn't have read access to any of the items or doesn't have write access to the destination folder, or if an unexpected error occurs

      • copyFolders

        java.util.List<java.lang.String> copyFolders​(java.util.List<java.lang.String> folders,
                                             java.lang.String destinationFolder,
                                             LibraryConflictResolution conflictResolution)
                                      throws LibraryServiceException
        Copies the given folders to the given destination folder. If the destination folder doesn't exist it will create it. This operation uses copyItems(List, Guid, LibraryConflictResolution) internally and is only provided for convenience.
        Parameters:
        folders - the paths of the library folders to copy
        destinationFolder - the path of the destination folder, must not be null.
        conflictResolution - the conflict resolution algorithm to use on any ID or path conflicts, must not be null
        Returns:
        the paths to the newly copied folders
        Throws:
        LibraryServiceException - if any of the items to be copied doesn't exist, if the calling user doesn't have read access to any of the folders or doesn't have write access to the destination folder, or if an unexpected error occurs
        Since:
        6.5.1

      • moveItems

        java.util.List<LibraryItem> moveItems​(java.util.List<Guid> itemIds,
                                      Guid destinationFolderId,
                                      LibraryConflictResolution conflictResolution)
                               throws LibraryServiceException
        Moves the given items to the given destination folder.
        Parameters:
        itemIds - the IDs of the library items to move
        destinationFolderId - the ID of the destination folder, must not be null
        conflictResolution - the conflict resolution algorithm to use on any ID or path conflicts, must not be null
        Returns:
        the newly moved items
        Throws:
        LibraryServiceException - if the destination folder or any of the items to be moved doesn't exist, if the calling user doesn't have read access to any of the items or doesn't have write access to the destination folder, or if an unexpected error occurs

      • removeItems

        void removeItems​(java.util.List<Guid> itemIds)
          throws LibraryServiceException
        Removes the given items.
        Parameters:
        itemIds - the IDs of the items to remove
        Throws:
        LibraryServiceException - if the calling user doesn't have write access to any of the items or if an unexpected error occurs

      • pathToId

        Guid pathToId​(java.lang.String path,
              java.lang.String type)
       throws LibraryServiceException
        Returns the ID of the item of the given type in the given location.
        Parameters:
        path - the location of the item, a path starts with a slash and each component is separated with a slash as well
        type - the type of the item
        Returns:
        the ID of an item or null if no such item exists
        Throws:
        LibraryServiceException - if an unexpected error occurs

      • idToPath

        java.lang.String idToPath​(Guid itemId)
                   throws LibraryServiceException
        Returns the path to the given library item.
        Parameters:
        itemId - the ID of the library item, must not be null
        Returns:
        the path to the given library item
        Throws:
        LibraryServiceException - if the item doesn't exist, if the calling user doesn't have read access to the item or if an unexpected error occurs

      • getPermissions

        AclEntryCollection getPermissions​(Guid itemId)
                           throws LibraryServiceException
        Returns the effective permissions of the given library item.
        Parameters:
        itemId - the ID of the library item, must not be null
        Returns:
        the effective permissions of the given library item
        Throws:
        LibraryServiceException - if the item doesn't exist, if the calling user doesn't have read access to the item or if an unexpected error occurs

      • setPermissions

        void setPermissions​(Guid itemId,
                    AclEntryCollection aclEntryCollection)
             throws LibraryServiceException
        Sets the permissions on the given library item. If the list is empty the permissions on the item is effectively cleared and it will inherit its permissions instead.
        Parameters:
        itemId - the ID of the library item, must not be null
        aclEntryCollection - a collection of Access Control List (ACL) entries for the given item, each ACL entry must have a principal name and at least one permission
        Throws:
        LibraryServiceException - if the item doesn't exist, if the calling user doesn't have owner access to the item or if an unexpected error occurs

      • clearPermissions

        void clearPermissions​(Guid itemId,
                      boolean includeDescendants)
               throws LibraryServiceException
        Clears the permissions on the given library item (and possibly on all of its descendants) meaning that the item will inherit its permissions instead.
        Parameters:
        itemId - the ID of the library item, must not be null
        includeDescendants - true if the permissions on any descendants should be cleared as well, false otherwise
        Throws:
        LibraryServiceException - if the item doesn't exist, if the calling user doesn't have owner access to the item or if an unexpected error occurs