Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.bookpac.server.document
Interface IWSDocMgmt

All Superinterfaces:
IWS
public interface IWSDocMgmt
extends IWS

Single document management web service interface.

Author:
rvuine

Method Summary
 void addDocumentAttributeCategory(String token, ArrayList<String> documentIDs, String categoryID)
          Adds an attribute category to the given document.
 void changeDocumentAttributes(String token, ArrayList<String> documentIDs, WSTMap attributes)
          Changes a number of document attributes.
 void changeDocumentBasketPosition(String token, String basketID, String documentID, int quantity)
          Changes a basket position for a document.
 void changeDocumentLanguage(String token, ArrayList<String> documentIDs, String languageCode)
          Changes the language property of a document -- language is not a conventional attribute, but a fundamental document property.
 void changeDocumentLicense(String token, String documentID, String licenseKey, boolean keepExistingLicenses)
          sets the license to a document
 void changeDocumentTags(String token, ArrayList<String> documentIDs, ArrayList<String> tagsToAdd, ArrayList<String> tagsToRemove)
          Changes the document's tags.
 void changeDocumentUserProperties(String token, String documentID, boolean master, WSTMap userProperties)
          Changes the user-specific (view) properties of a document.
 WSTCopyResult copyDocumentsFromKnownUser(String token, ArrayList<String> documentIDs)
          Copies a list of documents owned by someone else to the user's account.
 String createDocument(String token, String displayName, ArrayList<String> categoryIDs, WSTMap attributes, ArrayList<String> tags)
          Creates a new, empty document (a document that doesn't have any versions, that is, does not have any binary data associated with)
 String createDocumentFromWeb(String token, String documentURL, String displayName, ArrayList<String> categoryIDs, WSTMap attributes, ArrayList<String> tags)
          Creates a new document with a first version (a binary) fetched from the web.
 String fulfillDocument(String token, String documentID, String userName, String clientMarker, String affiliateID, String externalTransactionID)
          Fulfills a single commercial document to a user's account.
 ArrayList<String> getAllDocumentIDs(String token, boolean alsoRemoved)
          Returns a list of all document ids of the current user
 ArrayList<String> getAllDocumentIDsConstrained(String token, String search)
          Returns a list of own documents that belong to the current user and are within the given constraints.
 ArrayList<WSTDocument> getAllDocuments(String token, boolean alsoRemoved, int offset, int count)
          Returns a list of all documents of the current user.
 ArrayList<WSTDocument> getAllDocumentsConstrained(String token, String search, int offset, int count)
          Returns a list of own documents that belong to the current user and fulfill the given constraints.
 String getCatalogDocumentID(String token, String ean)
          Find a catalog document with the given EAN (ISBN).
 WSTDocument getDocument(String token, String documentID)
          Returns a document and version information for all versions.
 WSTDocumentAccessDescriptor getDocumentAccessDescriptor(String token, String documentID)
          Returns a WSTDocumentAccessDescriptor object that describes if the given document could be accessed by the current user, and, if not, why.
 ArrayList<WSTDocumentAccessDescriptor> getDocumentAccessDescriptors(String token, ArrayList<String> documentIDs)
          Returns a list of WSTDocumentAccessDescriptor objects that describe if the given documents could be accessed by the current user, and, if not, why.
 WSTDocument getDocumentByOriginalURL(String token, String originalURL)
          Returns a document information.
 ArrayList<WSTDocument> getDocuments(String token, ArrayList<String> documentIDs)
          Returns a list of document objects
 ArrayList<WSTDocument> getDocumentsFeaturedAs(String token, String feature, int offset, int count)
          Deprecated. use getDocumentsInContentPresentation(String, String, String, int, int) instead
 ArrayList<WSTDocument> getDocumentsInContentCategory(String token, String contentCategoryID, boolean includeSubCategories, String sortBy, boolean invert, int offset, int count)
          Returns a list of document objects, as contained in a content category.
 ArrayList<WSTDocument> getDocumentsInContentCategoryBySearchSource(String token, String contentCategoryID, boolean includeSubCategories, String search, ArrayList<String> sources, String sortBy, boolean invert, int offset, int count)
          Returns a list of document objects, as contained in a content category.
 ArrayList<WSTDocument> getDocumentsInContentCategoryConstrained(String token, String contentCategoryID, boolean includeSubCategories, String search, String sortBy, boolean invert, int offset, int count)
          Returns a list of document objects, as contained in a content category.
 ArrayList<WSTDocument> getDocumentsInContentPresentation(String token, String affiliateID, String presentationID, int offset, int count)
          Deprecated. use IWSFeaturedContentMgmt.getContentPresentationDocuments(String, String, String, int, int, String, boolean) instead
 ArrayList<WSTDocument> getDocumentsInList(String token, String listID, int offset, int count)
          Returns a list of document objects, as contained in a list.
 ArrayList<WSTDocument> getDocumentsRecommendedForUser(String token, int offset, int count)
          Returns a list of document objects that are related to the given document.
 ArrayList<WSTDocument> getDocumentsRelatedToDocument(String token, String documentID, int offset, int count)
          Returns a list of document objects that are related to the given document.
 WSTDocumentStatistics getDocumentStatistics(String token, String documentID)
          Get some statistics on the requested document.
 HashMap<String,String> getPotentialDocumentAttributeCategories(String token, String documentID)
          Returns a map: category UID to localized display name of the attribute categories that could be added to the document
 ArrayList<String> getUnlistedDocumentIDs(String token)
          Returns a list of documents IDs of all documents that are not in any list
 WSTDocumentFulfillablilityCode isDocumentFulfillable(String token, String documentID)
          Is the fulfillment of the given catalog document possible, or not? Checks, if specific restrictions (e.g.
 void prepareDocumentFormat(String token, String documentID, long versionID, String format)
          Prepare a given format for a document and version for delivery.
 void removeAllPreviews(String token, String documentID)
          Removes all previews of the given document regardless of format.
 void removeDocumentAttributeCategory(String token, ArrayList<String> documentIDs, String categoryID)
          Removes an attribute category from the given document.
 void removeDocuments(String token, ArrayList<String> documentIDs)
          Removes a list of document objects.
 void removeDocumentsInList(String token, String listID, boolean keepDocumentsInOtherLists)
          Removes a number of documents in a list (not merely from the list -- the documents will be removed!)
 void resetUserDocumentOriginalUrl(String token, String documentId, String newOriginalUrl)
          Reset a document by removing the acsm blob of the document and then replacing the old original url by the given new one, if it is null.
 WSTDocument revertDocumentToVersion(String token, String documentID, long versionID)
          Reverts a given document to the given version.
 void sendDocumentInvite(String token, ArrayList<String> documentIDs, ArrayList<String> eMailAddresses, ArrayList<String> userNames, boolean doCopyAlways, String message)
          Invites the given eMail addresses and user names to look a the given documents.
 void setDocumentTitleImageFromWeb(String token, String documentID, String imageURL)
          Imports a title image from the web and makes it the title image of a given document.
 ArrayList<String> suggestTitleImages(String token, String documentID)
          Suggests title images for a document.
 

Method Detail

createDocument

String createDocument(String token,
                      String displayName,
                      @Nullable
                      ArrayList<String> categoryIDs,
                      WSTMap attributes,
                      @Nullable
                      ArrayList<String> tags)
                      throws WSException
Creates a new, empty document (a document that doesn't have any versions, that is, does not have any binary data associated with)

Parameters:
token - the session ID, must be != null and valid
displayName - the display name to be used for the document. If you set title and author attributes, this may be null or empty and will be created automatically.
categoryIDs - the IDs of the attribute categories to be added to the document. May be empty or null, in which case only the default attribute category will be added.
attributes - the attributes (from the given categories) to be set. May be empty or null, in which case no attributes will be set.
tags - a list of tags, may be empty or null to set no tags
Returns:
the newly created document ID
Throws:
WSException - if an error occurs

createDocumentFromWeb

String createDocumentFromWeb(String token,
                             String documentURL,
                             @Nullable
                             String displayName,
                             @Nullable
                             ArrayList<String> categoryIDs,
                             @Nullable
                             WSTMap attributes,
                             @Nullable
                             ArrayList<String> tags)
                             throws WSException
Creates a new document with a first version (a binary) fetched from the web. If fetching from the web fails, the document will not be created and an exception will be thrown. The Document will be put into the users INBOX

Parameters:
token - the session ID, must be != null and valid
documentURL - the URL of the binary that is to be used as a first version of the document. This needs to be a valid URL. The type of the document will be auto-detected.
displayName - the display name to be used for the document. If you set title and author attributes, this may be null or empty and will be created automatically.
categoryIDs - the IDs of the attribute categories to be added to the document. May be empty or null, in which case only the default attribute category will be added.
attributes - the attributes (from the given categories) to be set. May be empty or null, in which case no attributes will be set but those that can be discovered from the binary document. If you set attributes that have also discovered values, the values set in this method will override the discovered values.
tags - a list of tags, may be empty or null to set no tags
Returns:
the newly created document ID
Throws:
WSException - if an error occurs

getAllDocumentIDs

ArrayList<String> getAllDocumentIDs(String token,
                                    boolean alsoRemoved)
                                    throws WSException
Returns a list of all document ids of the current user

Parameters:
token - the session ID, must be != null and valid
alsoRemoved - get also the removed document IDs
Returns:
a list of document IDs, may be empty, but never null
Throws:
WSException - if an error occurs

getUnlistedDocumentIDs

ArrayList<String> getUnlistedDocumentIDs(String token)
                                         throws WSException
Returns a list of documents IDs of all documents that are not in any list

Parameters:
token - the session ID, must be != null and valid
Returns:
a list of list IDs, may be empty, but never null
Throws:
WSException - if an error occurs

getAllDocumentIDsConstrained

ArrayList<String> getAllDocumentIDsConstrained(String token,
                                               String search)
                                               throws WSException
Returns a list of own documents that belong to the current user and are within the given constraints. The constraint syntax is the same as for the IWSListMgmt getListConstrained method.

Parameters:
token - a valid token
search - the search String. This is either a plain String to search all attributes, or a fielded String like "field:value". All attribute IDs are valid field IDs. You can also user their lower-cased English localizations, so "author:gaddis" is equivalent to "20514d7d-7591-49a4-a62d-f5c02a8f5edd:gaddis". There are some special (non-attribute) fields: currentVersionFormat, currentVersionNumber, originalURL, displayName and fileName. Search terms separated by spaces are ANDed. Boolean Operators OR and AND NOT are allowed, so are brackets.

A search returning all PDF documents written by Gaddis would be "author:Gaddis AND currentVersionFormat:PDF", using the author attribute and the currentVersionFormat special field.

Returns:
a list of document IDs, which may be empty, but never null
Throws:
WSException - if an error occurs

getAllDocuments

ArrayList<WSTDocument> getAllDocuments(String token,
                                       boolean alsoRemoved,
                                       int offset,
                                       int count)
                                       throws WSException
Returns a list of all documents of the current user.

Parameters:
token - the session ID, must be != null and valid
alsoRemoved - should removed documents also be returned?
offset - the offset of the first document to be returned
count - the number of documents to be returned, may be -1 to indicate that all documents should be returned
Returns:
a list of document objects, may be empty, but never null
Throws:
WSException - if an error occurs

getAllDocumentsConstrained

ArrayList<WSTDocument> getAllDocumentsConstrained(String token,
                                                  String search,
                                                  int offset,
                                                  int count)
                                                  throws WSException
Returns a list of own documents that belong to the current user and fulfill the given constraints. The constraint syntax is the same as for the IWSListMgmt getListConstrained method.

Parameters:
token - the sessionID of the user to return the documents for
search - the search String. This is either a plain String to search all attributes, or a fielded String like "field:value". All attribute IDs are valid field IDs. You can also user their lower-cased English localizations, so "author:gaddis" is equivalent to "20514d7d-7591-49a4-a62d-f5c02a8f5edd:gaddis". There are some special (non-attribute) fields: currentVersionFormat, currentVersionNumber, originalURL, displayName and fileName. Search terms separated by spaces are ANDed. Boolean Operators OR and AND NOT are allowed, so are brackets.

A search returning all PDF documents written by Gaddis would be "author:Gaddis AND currentVersionFormat:PDF", using the author attribute and the currentVersionFormat special field.

offset - the offset of the first document to be returned
count - the number of documents to be returned, may be -1 to indicate that all documents should be returned
Returns:
a list of documents, which may be empty, but never null
Throws:
WSException - if an error occurs

getDocuments

ArrayList<WSTDocument> getDocuments(String token,
                                    ArrayList<String> documentIDs)
                                    throws WSException
Returns a list of document objects

Parameters:
token - the session ID, must be != null and valid
documentIDs - a list of IDs of the documents to be returned
Returns:
a list of document objects, may be empty, but never null
Throws:
WSException - if an error occurs

getDocumentAccessDescriptors

ArrayList<WSTDocumentAccessDescriptor> getDocumentAccessDescriptors(String token,
                                                                    ArrayList<String> documentIDs)
                                                                    throws WSException
Returns a list of WSTDocumentAccessDescriptor objects that describe if the given documents could be accessed by the current user, and, if not, why.

Parameters:
token - the session ID, must be != null and valid
documentIDs - the IDs of the documents to be checked.
Returns:
an access descriptor stating if the document can be opened by the current user, and if not, why.
Throws:
WSException

getDocument

WSTDocument getDocument(String token,
                        String documentID)
                        throws WSException
Returns a document and version information for all versions. Will return null if the document cannot be accessed. The reason for the documents inaccessibility can be determined by calling getDocumentAccessDescriptor(...)

Parameters:
token - the session ID, must be != null and valid
documentID - the ID of the document to be returned
Returns:
a document object or null if this document cannot be opened by the current user for whatever reason (it doesn't exist, or the user has no access rights).
Throws:
WSException - if an error occurs

getDocumentByOriginalURL

WSTDocument getDocumentByOriginalURL(String token,
                                     String originalURL)
                                     throws WSException
Returns a document information. Will return null if the document cannot be accessed. The reason for the documents inaccessibility can be determined by calling getDocumentAccessDescriptor(...)

Parameters:
token - the session ID, must be != null and valid
originalURL - the originalURL according to of the document to be returned, must not be null
Returns:
the document with the given originalURL or null if the given user has no document with the given URL
Throws:
WSException - if the given token is invalid or the given URL is not

getDocumentAccessDescriptor

WSTDocumentAccessDescriptor getDocumentAccessDescriptor(String token,
                                                        String documentID)
                                                        throws WSException
Returns a WSTDocumentAccessDescriptor object that describes if the given document could be accessed by the current user, and, if not, why.

Parameters:
token - the session ID, must be != null and valid
documentID - the ID of the document to be checked.
Returns:
an access descriptor stating if the document can be opened by the current user, and if not, why.
Throws:
WSException - if an error occurs

getDocumentsInList

ArrayList<WSTDocument> getDocumentsInList(String token,
                                          String listID,
                                          int offset,
                                          int count)
                                          throws WSException
Returns a list of document objects, as contained in a list.

Parameters:
token - the session ID, must be != null and valid
listID - the ID of the list where the documents reside, must be valid and the current user must be able to access the list.
offset - the index of the first document to be returned
count - the number of objects to be returned, may be -1 to indicate that all documents are to be returned.
Returns:
a list of document objects, may be empty, but never null
Throws:
WSException - if an error occurs

getDocumentsInContentCategory

ArrayList<WSTDocument> getDocumentsInContentCategory(String token,
                                                     String contentCategoryID,
                                                     boolean includeSubCategories,
                                                     @Nullable
                                                     String sortBy,
                                                     boolean invert,
                                                     int offset,
                                                     int count)
                                                     throws WSException
Returns a list of document objects, as contained in a content category.

Parameters:
token - the session ID, must be != null and valid
contentCategoryID - the ID of the content category where the documents reside
includeSubCategories - if the documents of sub categories should be returned, too
sortBy - sort the documents by this search field, may be null
invert - if true, sorting order will be reversed
offset - the index of the first document to be returned
count - the number of objects to be returned, may be -1 to indicate that all documents are to be returned.
Returns:
a list of document objects, may be empty, but never null
Throws:
WSException - if an error occurs

getDocumentsInContentCategoryConstrained

ArrayList<WSTDocument> getDocumentsInContentCategoryConstrained(String token,
                                                                String contentCategoryID,
                                                                boolean includeSubCategories,
                                                                @Nullable
                                                                String search,
                                                                @Nullable
                                                                String sortBy,
                                                                boolean invert,
                                                                int offset,
                                                                int count)
                                                                throws WSException
Returns a list of document objects, as contained in a content category.

Parameters:
token - the session ID, must be != null and valid
contentCategoryID - the ID of the content category where the documents reside
includeSubCategories - if the documents of sub categories should be returned, too
search - the search String. This is either a plain String to search all attributes, or a fielded String like "field:value". All attribute IDs are valid field IDs. You can also user their lower-cased English localizations, so "author:gaddis" is equivalent to "20514d7d-7591-49a4-a62d-f5c02a8f5edd:gaddis". There are some special (non-attribute) fields: currentVersionFormat, currentVersionNumber, originalURL, displayName and fileName. Search terms separated by spaces are ANDed. Boolean Operators OR and AND NOT are allowed, so are brackets.

A search returning all PDF documents written by Gaddis would be "author:Gaddis AND currentVersionFormat:PDF", using the author attribute and the currentVersionFormat special field.

sortBy - sort the documents by this search field, may be null
invert - if true, sorting order will be reversed
offset - the index of the first document to be returned
count - the number of objects to be returned, may be -1 to indicate that all documents are to be returned.
Returns:
a list of document objects, may be empty, but never null
Throws:
WSException - if an error occurs

getDocumentsInContentCategoryBySearchSource

ArrayList<WSTDocument> getDocumentsInContentCategoryBySearchSource(String token,
                                                                   String contentCategoryID,
                                                                   boolean includeSubCategories,
                                                                   @Nullable
                                                                   String search,
                                                                   @Nullable
                                                                   ArrayList<String> sources,
                                                                   @Nullable
                                                                   String sortBy,
                                                                   boolean invert,
                                                                   int offset,
                                                                   int count)
                                                                   throws WSException
Returns a list of document objects, as contained in a content category.

Parameters:
token - the session ID, must be != null and valid
contentCategoryID - the ID of the content category where the documents reside
includeSubCategories - if the documents of sub categories should be returned, too
search - the search String. This is either a plain String to search all attributes, or a fielded String like "field:value". All attribute IDs are valid field IDs. You can also user their lower-cased English localizations, so "author:gaddis" is equivalent to "20514d7d-7591-49a4-a62d-f5c02a8f5edd:gaddis". There are some special (non-attribute) fields: currentVersionFormat, currentVersionNumber, originalURL, displayName and fileName. Search terms separated by spaces are ANDed. Boolean Operators OR and AND NOT are allowed, so are brackets.

A search returning all PDF documents written by Gaddis would be "author:Gaddis AND currentVersionFormat:PDF", using the author attribute and the currentVersionFormat special field.

sources - see WSTDocumentSearchSource, excluding WSTDocumentSearchSource.OWN and WSTDocumentSearchSource.OTHER
sortBy - sort the documents by this search field, may be null
invert - if true, sorting order will be reversed
offset - the index of the first document to be returned
count - the number of objects to be returned, may be -1 to indicate that all documents are to be returned.
Returns:
a list of document objects, may be empty, but never null
Throws:
WSException - if an exception occurs

getDocumentsRelatedToDocument

ArrayList<WSTDocument> getDocumentsRelatedToDocument(String token,
                                                     String documentID,
                                                     int offset,
                                                     int count)
                                                     throws WSException
Returns a list of document objects that are related to the given document.

Parameters:
token - the session ID, must be != null and valid
documentID - the ID of the document to be used for determining related documents
offset - the index of the first document to be returned. This parameter is ignored in the current implementation.
count - the number of objects to be returned, must be a positive value.
Returns:
a list of document objects, may be empty, but never null
Throws:
WSException - if an error occurs

getDocumentsRecommendedForUser

ArrayList<WSTDocument> getDocumentsRecommendedForUser(String token,
                                                      int offset,
                                                      int count)
                                                      throws WSException
Returns a list of document objects that are related to the given document.

Parameters:
token - the session ID, must be != null and valid
offset - the index of the first document to be returned. This parameter is ignored in the current implementation.
count - the number of objects to be returned, must be a positive value.
Returns:
a list of document objects, may be empty, but never null
Throws:
WSException

getDocumentsFeaturedAs

@Deprecated
ArrayList<WSTDocument> getDocumentsFeaturedAs(String token,
                                                         String feature,
                                                         int offset,
                                                         int count)
                                              throws WSException
Deprecated. use getDocumentsInContentPresentation(String, String, String, int, int) instead

Returns a list of documents that are in lists featured with the given feature IDs

Parameters:
token - the session ID, must be != null and valid
feature - the ID of the feature to be used for determining the documents to be returned
offset - the index of the first document to be returned
count - the number of objects to be returned, may be -1 to indicate that all documents are to be returned.
Returns:
a list of document objects, may be empty, but never null
Throws:
WSException

getDocumentsInContentPresentation

@Deprecated
ArrayList<WSTDocument> getDocumentsInContentPresentation(String token,
                                                                    String affiliateID,
                                                                    String presentationID,
                                                                    int offset,
                                                                    int count)
                                                         throws WSException
Deprecated. use IWSFeaturedContentMgmt.getContentPresentationDocuments(String, String, String, int, int, String, boolean) instead

Returns a list of documents that are contained in the content presentation for the given affiliate and presentation ID.

Parameters:
token - the valid session ID
affiliateID - the ID of the affiliate who wants to display the presentation, may be null
presentationID - the ID of the presentation
offset - offset of the first document to be returned
count - the maximum number of documents to be returned, may be -1 to indicate that all documents (up to the defined max list size) may be returned.
Returns:
a list of documents that may be empty but never null
Throws:
WSException - if the requested offset is out of bounds

removeDocuments

void removeDocuments(String token,
                     ArrayList<String> documentIDs)
                     throws WSException
Removes a list of document objects. Like the other methods, this is transactional: If one of the delete operation fails and you get an exception, no documents will be deleted.

Parameters:
token - the session ID, must be != null and valid
documentIDs - a list of IDs of the documents to be removed.
Throws:
WSException - if an error occurs

removeDocumentsInList

void removeDocumentsInList(String token,
                           String listID,
                           boolean keepDocumentsInOtherLists)
                           throws WSException
Removes a number of documents in a list (not merely from the list -- the documents will be removed!)

Parameters:
token - the session ID, must be != null and valid
listID - a list ID
keepDocumentsInOtherLists - if true, the documents will not be removed if they still are listed in other lists, but only de-listed from the given list. If false, the documents will be removed without taking other lists into account, effectively making them disappear from all lists.
Currently only true is supported!
Throws:
WSException - if an error occurs

sendDocumentInvite

void sendDocumentInvite(String token,
                        ArrayList<String> documentIDs,
                        ArrayList<String> eMailAddresses,
                        ArrayList<String> userNames,
                        boolean doCopyAlways,
                        String message)
                        throws WSException
Invites the given eMail addresses and user names to look a the given documents.

If doCopyAlways is true, the receivers will get copies of the documents. (The eMail addresses will receive links to copies of the document that can be grabbed by executing action requests that will be created along with the copies of the document.)

If doCopyAlways is false, this method will send out links to all public documents and to documents that can be accessed (via permissions) by each receiving txtr user. Setting doCopyAlways to false means "do only make copies of the document if such a step is necessary to show the document to the receiver".

Parameters:
token - the current session ID of the user
documentIDs - the list of IDs of the document that the users should be invited to see. The current user must be allowed to see the document.
eMailAddresses - the eMail addresses to send the invitations out to
userNames - the user IDs that shall receive the invitation
doCopyAlways - if true, copies of the document will be generated even if the receivers could (by permission) access the original. recipients.
message - a message to be sent out along with the invitations.
Throws:
WSException - if an error occurs

copyDocumentsFromKnownUser

WSTCopyResult copyDocumentsFromKnownUser(String token,
                                         ArrayList<String> documentIDs)
                                         throws WSException
Copies a list of documents owned by someone else to the user's account.

Parameters:
token - the current session ID of the user
documentIDs - the IDs of documents owned by some other user that shall be copied to the user's account.
Returns:
a WSTCopyResult object, never null
Throws:
WSException - if an error occurs

changeDocumentAttributes

void changeDocumentAttributes(String token,
                              ArrayList<String> documentIDs,
                              WSTMap attributes)
                              throws WSException
Changes a number of document attributes. The hash is a map of attribute UID to new value. Attributes that the document does not have will be silently ignored. For adding attributes, use addDocumentAttributeCategory() method.

Parameters:
token - the current session ID of the user
documentIDs - the IDs of the documents, must not be null
attributes - the attributes to be set
Throws:
WSException - if an error occurs

changeDocumentTags

void changeDocumentTags(String token,
                        ArrayList<String> documentIDs,
                        ArrayList<String> tagsToAdd,
                        ArrayList<String> tagsToRemove)
                        throws WSException
Changes the document's tags.

Parameters:
token - the current session ID of the user
documentIDs - the IDs of the documents, must not be null
tagsToAdd - the tags to be added, values truncated to 1024 bytes
tagsToRemove - the tags to be removed
Throws:
WSException - if an error occurs

changeDocumentLanguage

void changeDocumentLanguage(String token,
                            ArrayList<String> documentIDs,
                            String languageCode)
                            throws WSException
Changes the language property of a document -- language is not a conventional attribute, but a fundamental document property.

Parameters:
token - the current session ID of the user
documentIDs - the IDs of the documents, must not be null
languageCode - the code of the language that the give documents are written in. Accepted values are two-letter lower-case language codes, java-style.
Throws:
WSException - if an error occurs

getPotentialDocumentAttributeCategories

HashMap<String,String> getPotentialDocumentAttributeCategories(String token,
                                                               String documentID)
                                                               throws WSException
Returns a map: category UID to localized display name of the attribute categories that could be added to the document

Parameters:
token - the current session ID of the user
documentID - the ID of the document, must not be null
Returns:
a map of IDs to display names
Throws:
WSException - if an error occurs

addDocumentAttributeCategory

void addDocumentAttributeCategory(String token,
                                  ArrayList<String> documentIDs,
                                  String categoryID)
                                  throws WSException
Adds an attribute category to the given document.

Parameters:
token - the current session ID of the user
documentIDs - the IDs of the documents, must not be null
categoryID - the ID of the category as returned by getPotentialDocumentAttributeCategories()
Throws:
WSException - if an error occurs

removeDocumentAttributeCategory

void removeDocumentAttributeCategory(String token,
                                     ArrayList<String> documentIDs,
                                     String categoryID)
                                     throws WSException
Removes an attribute category from the given document.

Parameters:
token - the current session ID of the user
documentIDs - the IDs of the documents, must not be null
categoryID - the ID of the category
Throws:
WSException - if an error occurs

revertDocumentToVersion

WSTDocument revertDocumentToVersion(String token,
                                    String documentID,
                                    long versionID)
                                    throws WSException
Reverts a given document to the given version. No versions will be lost, the given version will be added as new current version.

Parameters:
token - the token
documentID - the ID of the document to be reverted
versionID - the version ID of the version to revert to.
Returns:
the updated document object
Throws:
WSException - if an error occurs

prepareDocumentFormat

void prepareDocumentFormat(String token,
                           String documentID,
                           long versionID,
                           String format)
                           throws WSException
Prepare a given format for a document and version for delivery.

Parameters:
token - the token
documentID - the ID of the document of the format
versionID - the ID of the version of the document
format - the format to be prepared
Throws:
WSException - if an error occurs

suggestTitleImages

ArrayList<String> suggestTitleImages(String token,
                                     String documentID)
                                     throws WSException
Suggests title images for a document. This will return a list of URLs from various sources, such as txtr.com, or amazon.

Parameters:
token - a valid token
documentID - a document ID
Returns:
a list of potential title image URLs, which may be empty, but never null
Throws:
WSException - if an error occurs

setDocumentTitleImageFromWeb

void setDocumentTitleImageFromWeb(String token,
                                  String documentID,
                                  String imageURL)
                                  throws WSException
Imports a title image from the web and makes it the title image of a given document.

Parameters:
token - a valid token
documentID - the documentID
imageURL - the URL of the image. Must resolve to a image, which must be either JPEG or PNG, and be of a sensible size (< 2 MB)
Throws:
WSException - if an error occurs

changeDocumentLicense

void changeDocumentLicense(String token,
                           String documentID,
                           String licenseKey,
                           boolean keepExistingLicenses)
                           throws WSException
sets the license to a document

Parameters:
token - a valid token
documentID - the document ID
licenseKey - key of the master license, may be null to add no license (only makes sense when keepExistingLicenses=false)
keepExistingLicenses - if we should keep existing licenses
Throws:
WSException - if an error occurs

changeDocumentUserProperties

void changeDocumentUserProperties(String token,
                                  String documentID,
                                  boolean master,
                                  WSTMap userProperties)
                                  throws WSException
Changes the user-specific (view) properties of a document. If the master flag is set and the user is the owner of the document, other users will be able to see the properties if they didn't specify their own already.

Parameters:
token - the session ID, must be != null and valid
documentID - the ID of the document to be checked.
master - should the passed properties be visible to other users? (only available if this user is the owner of the document)
userProperties - the properties to be set.
Throws:
WSException - if an error occurs

changeDocumentBasketPosition

void changeDocumentBasketPosition(String token,
                                  String basketID,
                                  String documentID,
                                  int quantity)
                                  throws WSException
Changes a basket position for a document. Setting a basket position's quantity to zero or null will remove the position.

Parameters:
token - a valid token
basketID - the basket where the document position should be changed, may be null to use the default basket (is created automatically)
documentID - the document ID
quantity - the desired quantity
Throws:
WSException - if an error occurs

fulfillDocument

String fulfillDocument(String token,
                       String documentID,
                       String userName,
                       String clientMarker,
                       String affiliateID,
                       String externalTransactionID)
                       throws WSException
Fulfills a single commercial document to a user's account. If the calling user has the right to call this method, this will trigger a commercial transaction, successful or failing, that will be included in the transaction report. Successful transactions will typically be billed to the caller of this method. For re-downloads of documents that have already been fulfilled to a user's account, the same download link should be re-used. More calls to this method will trigger separate, billable, commercial transactions.

Parameters:
token - a token that identifies a user that has the right to trigger fulfillment operations
documentID - the ID of the commercial document to be fulfilled
userName - the unique identifier / login of the user who should receive the document, must not be null
clientMarker - a client marker indicating the kind of client. Use short, lower-case markers, e.g. "iphone" May be empty.
affiliateID - an affiliate ID that will show up in transaction reports, may be empty
externalTransactionID - an external transaction ID that will show up in reports for this fulfillment/checkout operation
Returns:
the ID of the newly created document in the user's account.
Throws:
WSException - if an error occurs

removeAllPreviews

void removeAllPreviews(String token,
                       String documentID)
                       throws WSException
Removes all previews of the given document regardless of format. The preview blobs will be deleted as well.

Parameters:
token - the token of a user that can modify the given document.
documentID - a document id.
Throws:
WSException - in case of errors.

getDocumentStatistics

WSTDocumentStatistics getDocumentStatistics(String token,
                                            String documentID)
                                            throws WSException
Get some statistics on the requested document.

Parameters:
token - a token with right USE_BACKEND.
documentID - a document id
Returns:
a statistics object, with possibly zero or empty values.
Throws:
WSException - in case of errors.

getCatalogDocumentID

String getCatalogDocumentID(String token,
                            String ean)
                            throws WSException
Find a catalog document with the given EAN (ISBN).

Parameters:
token - a token used to resolve the catalog with right WSTRight.QUERY_CATALOG_DOCUMENT_IDS.
ean - an EAN
Returns:
a document id or null
Throws:
WSException - in case of errors

resetUserDocumentOriginalUrl

void resetUserDocumentOriginalUrl(String token,
                                  String documentId,
                                  String newOriginalUrl)
                                  throws WSException
Reset a document by removing the acsm blob of the document and then replacing the old original url by the given new one, if it is null.

Parameters:
token - a token with right EDIT_DOCUMENT_ATTRIBUTES
documentId - a document id
newOriginalUrl - a new original url, may be null, in which case, the old url won't be changed.
Throws:
WSException - in case of errors.

isDocumentFulfillable

WSTDocumentFulfillablilityCode isDocumentFulfillable(String token,
                                                     String documentID)
                                                     throws WSException
Is the fulfillment of the given catalog document possible, or not? Checks, if specific restrictions (e.g. territorial sale restrictions) apply to the user identified by the given token, i.e. would prevent a successful fulfillment.

Parameters:
token - a user token.
documentID - a catalog document id of a document in the catalog of the user's nature.
Returns:
a document fulfillability code.
Throws:
WSException - in case of errors.
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD