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 -
Method Summary
Modifier and TypeMethodDescriptionvoid
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.copyFolders
(List<String> folders, String destinationFolder, LibraryConflictResolution conflictResolution) Copies the given folders to the given destination folder.copyItems
(List<Guid> itemIds, Guid destinationFolderId, LibraryConflictResolution conflictResolution) Copies the given items to the given destination folder.createFolder
(String title, String description, Guid parentId) Creates a new folder.getChildItems
(Guid folderId) Returns all items (if any) within the given folder that the calling user has read access to.getChildItemsAsUser
(Guid folderId, UserName userName) Returns all items (if any) within the given folder that the given user has read access to.Returns the items with the given IDs that the calling user has read access to.getItemsAsUser
(List<Guid> itemIds, UserName userName) Returns the items with the given IDs that the given user has read access to.Returns all item types.getPermissions
(Guid itemId) Returns the effective permissions of the given library item.Returns the root item.Returns the path to the given library item.moveItems
(List<Guid> itemIds, Guid destinationFolderId, LibraryConflictResolution conflictResolution) Moves the given items to the given destination folder.Returns the ID of the item of the given type in the given location.void
removeItems
(List<Guid> itemIds) Removes the given items.searchItems
(String searchExpression, Guid locationId, int maxResults) Returns all items, up to the given limit, in the given location that matches the given search expression.searchItemsAsUser
(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, 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, Collection<LibraryProperty> properties) Sets the properties of the given library item.void
Sets the title of the given library item.
-
Field Details
-
SERVICE_SCOPE
The OAuth 2.0 scope needed to access any operation in this service.- Since:
- 7.13
- See Also:
-
IMPERSONATION_SCOPE
The OAuth 2.0 scope needed to access the operations in this service where another user is impersonated.
-
-
Method Details
-
getRootItem
Returns the root item.- Returns:
- the root item
- Throws:
LibraryServiceException
- if an unexpected error occurs
-
getChildItems
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
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 ofuserName
- 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
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
List<LibraryItem> getItemsAsUser(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 retrieveuserName
- 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
List<LibraryItem> searchItems(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 expressionlocationId
- the ID of a folder item in which to search (all subfolders will also be included) or null if the entire library should be searchedmaxResults
- 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
List<LibraryItem> searchItemsAsUser(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 expressionlocationId
- the ID of a folder item in which to search (all subfolders will also be included) or null if the entire library should be searchedmaxResults
- the maximum number of items to be returned or a number less than or equal to 0 if all matching items should be returneduserName
- 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
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.Example 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
- spotfire.sbdf - An sbdf file with data
- Returns:
- all item types
- Throws:
LibraryServiceException
- if an unexpected error occurs
-
createFolder
LibraryItem createFolder(String title, 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 charactersparentId
- 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
Sets the title of the given library item.- Parameters:
itemId
- the ID of the library item to set the title for, must not be nulltitle
- 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
Sets the description of the given library item.- Parameters:
itemId
- the ID of the library item to set the title for, must not be nulldescription
- 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, 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 nullproperties
- 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
List<LibraryItem> copyItems(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 copydestinationFolderId
- the ID of the destination folder, must not be nullconflictResolution
- 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
List<String> copyFolders(List<String> folders, 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 usescopyItems(List, Guid, LibraryConflictResolution)
internally and is only provided for convenience.- Parameters:
folders
- the paths of the library folders to copydestinationFolder
- 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
List<LibraryItem> moveItems(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 movedestinationFolderId
- the ID of the destination folder, must not be nullconflictResolution
- 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
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
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 welltype
- 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
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
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 nullaclEntryCollection
- 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
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 nullincludeDescendants
- 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
-