com.smartsheet.api.SheetResources Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of smartsheet-sdk-java Show documentation
Show all versions of smartsheet-sdk-java Show documentation
Library for connecting to Smartsheet Services
package com.smartsheet.api;
/*
* #[license]
* Smartsheet SDK for Java
* %%
* Copyright (C) 2014 Smartsheet
* %%
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
* %[license]
*/
import com.smartsheet.api.models.*;
import com.smartsheet.api.models.enums.*;
import java.io.OutputStream;
import java.util.Date;
import java.util.EnumSet;
import java.util.Set;
/**
* This interface provides methods to access Sheet resources.
*
* Thread Safety: Implementation of this interface must be thread safe.
*/
public interface SheetResources {
/**
* List all sheets.
*
* It mirrors to the following Smartsheet REST API method: GET /sheets
*
* @param includes the source inclusion
* @param pagination the object containing the pagination parameters
* @param modifiedSince restrict results to sheets modified on or after this date
* @return A list of all sheets (note that an empty list will be returned if there are none).
* @throws IllegalArgumentException if any argument is null or empty string
* @throws InvalidRequestException if there is any problem with the REST API request
* @throws AuthorizationException if there is any problem with the REST API authorization (access token)
* @throws ResourceNotFoundException if the resource cannot be found
* @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
* @throws SmartsheetException if there is any other error during the operation
*/
public PagedResult listSheets(EnumSet includes, PaginationParameters pagination, Date modifiedSince) throws SmartsheetException;
/**
* List all sheets.
*
* It mirrors to the following Smartsheet REST API method: GET /sheets
*
* @param includes the source inclusion
* @param pagination the object containing the pagination parameters
* @return A list of all sheets (note that an empty list will be returned if there are none).
* @throws IllegalArgumentException if any argument is null or empty string
* @throws InvalidRequestException if there is any problem with the REST API request
* @throws AuthorizationException if there is any problem with the REST API authorization (access token)
* @throws ResourceNotFoundException if the resource cannot be found
* @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
* @throws SmartsheetException if there is any other error during the operation
*/
@Deprecated
public PagedResult listSheets(EnumSet includes, PaginationParameters pagination) throws SmartsheetException;
/**
* List all sheets in the organization.
*
* It mirrors to the following Smartsheet REST API method: GET /users/sheets
*
* @param parameters the object containing the pagination parameters
* @return the list of all sheets (note that an empty list will be returned if there are none)
* @throws IllegalArgumentException if any argument is null or empty string
* @throws InvalidRequestException if there is any problem with the REST API request
* @throws AuthorizationException if there is any problem with the REST API authorization (access token)
* @throws ResourceNotFoundException if the resource cannot be found
* @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
* @throws SmartsheetException if there is any other error during the operation
*/
@Deprecated
public PagedResult listOrganizationSheets(PaginationParameters parameters) throws SmartsheetException;
/**
* Get a sheet.
*
* It mirrors to the following Smartsheet REST API method: GET /sheet/{id}
*
* @param id the id of the sheet
* @param includes used to specify the optional objects to include.
* @param columnIds the column ids
* @param excludes the exclude parameters
* @param page the page number
* @param pageSize the page size
* @param rowIds the row ids
* @param rowNumbers the row numbers
* @return the sheet resource (note that if there is no such resource, this method will throw
* ResourceNotFoundException rather than returning null).
* @throws IllegalArgumentException if any argument is null or empty string
* @throws InvalidRequestException if there is any problem with the REST API request
* @throws AuthorizationException if there is any problem with the REST API authorization (access token)
* @throws ResourceNotFoundException if the resource cannot be found
* @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
* @throws SmartsheetException if there is any other error during the operation
*/
public Sheet getSheet(long id,
EnumSet includes,
EnumSet excludes,
Set rowIds,
Set rowNumbers,
Set columnIds,
Integer pageSize,
Integer page) throws SmartsheetException;
/**
* Get a sheet as an Excel file.
*
* It mirrors to the following Smartsheet REST API method:
* GET /sheet/{id} with "application/vnd.ms-excel" Accept HTTP header
*
* @param id the id of the sheet
* @param outputStream the output stream to which the Excel file will be written.
* @throws IllegalArgumentException if any argument is null or empty string
* @throws InvalidRequestException if there is any problem with the REST API request
* @throws AuthorizationException if there is any problem with the REST API authorization (access token)
* @throws ResourceNotFoundException if the resource cannot be found
* @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
* @throws SmartsheetException if there is any other error during the operation
*/
public void getSheetAsExcel(long id, OutputStream outputStream) throws SmartsheetException;
/**
* Get a sheet as an Excel file.
*
* It mirrors to the following Smartsheet REST API method:
* GET /sheet/{id} with "application/vnd.ms-excel" Accept HTTP header
*
* @param id the id of the sheet
* @param outputStream the output stream to which the Excel file will be written.
* @throws IllegalArgumentException if any argument is null or empty string
* @throws InvalidRequestException if there is any problem with the REST API request
* @throws AuthorizationException if there is any problem with the REST API authorization (access token)
* @throws ResourceNotFoundException if the resource cannot be found
* @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
* @throws SmartsheetException if there is any other error during the operation
*/
public void getSheetAsCSV(long id, OutputStream outputStream) throws SmartsheetException;
/**
* Get a sheet as a PDF file.
*
* It mirrors to the following Smartsheet REST API method:
* GET /sheet/{id} with "application/pdf" Accept HTTP header
*
* @param id the id of the sheet
* @param outputStream the output stream to which the PDF file will be written.
* @param paperSize the paper size
* @throws IllegalArgumentException if any argument is null or empty string
* @throws InvalidRequestException if there is any problem with the REST API request
* @throws AuthorizationException if there is any problem with the REST API authorization (access token)
* @throws ResourceNotFoundException if the resource cannot be found
* @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
* @throws SmartsheetException if there is any other error during the operation
*/
public void getSheetAsPDF(long id, OutputStream outputStream, PaperSize paperSize) throws SmartsheetException;
/**
* Create a sheet in default "Sheets" collection.
*
* It mirrors to the following Smartsheet REST API method:
* POST /sheets
*
* @param sheet the sheet to created
* @return the created sheet
* @throws IllegalArgumentException if any argument is null or empty string
* @throws InvalidRequestException if there is any problem with the REST API request
* @throws AuthorizationException if there is any problem with the REST API authorization (access token)
* @throws ResourceNotFoundException if the resource cannot be found
* @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
* @throws SmartsheetException if there is any other error during the operation
*/
public Sheet createSheet(Sheet sheet) throws SmartsheetException;
/**
* Create a sheet (from existing sheet or template) in default "Sheets" collection.
*
* It mirrors to the following Smartsheet REST API method: POST /sheets
*
* @param sheet the sheet to create
* @param includes used to specify the optional objects to include.
* @return the created sheet
* @throws IllegalArgumentException if any argument is null or empty string
* @throws InvalidRequestException if there is any problem with the REST API request
* @throws AuthorizationException if there is any problem with the REST API authorization (access token)
* @throws ResourceNotFoundException if the resource cannot be found
* @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
* @throws SmartsheetException if there is any other error during the operation
*/
public Sheet createSheetFromTemplate(Sheet sheet, EnumSet includes) throws SmartsheetException;
/**
* Create a sheet in given folder.
*
* It mirrors to the following Smartsheet REST API method: POST /folders/{folderId}/sheets
*
* @param folderId the folder id
* @param sheet the sheet to create
* @return the created sheet
* @throws IllegalArgumentException if any argument is null or empty string
* @throws InvalidRequestException if there is any problem with the REST API request
* @throws AuthorizationException if there is any problem with the REST API authorization (access token)
* @throws ResourceNotFoundException if the resource cannot be found
* @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
* @throws SmartsheetException if there is any other error during the operation
*/
public Sheet createSheetInFolder(long folderId, Sheet sheet) throws SmartsheetException;
/**
* Create a sheet (from existing sheet or template) in given folder.
*
* It mirrors to the following Smartsheet REST API method: POST /folders/{folderId}/sheets
*
* @param folderID the folder id
* @param sheet the sheet to create
* @param includes used to specify the optional objects to include.
* @return the created sheet
* @throws IllegalArgumentException if any argument is null or empty string
* @throws InvalidRequestException if there is any problem with the REST API request
* @throws AuthorizationException if there is any problem with the REST API authorization (access token)
* @throws ResourceNotFoundException if the resource cannot be found
* @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
* @throws SmartsheetException if there is any other error during the operation
*/
public Sheet createSheetInFolderFromTemplate(long folderID, Sheet sheet, EnumSet includes) throws SmartsheetException;
/**
* Create a sheet in given workspace.
*
* It mirrors to the following Smartsheet REST API method: POST /workspace/{workspaceId}/sheets
*
* @param workspaceId the workspace id
* @param sheet the sheet to create
* @return the created sheet
* @throws IllegalArgumentException if any argument is null or empty string
* @throws InvalidRequestException if there is any problem with the REST API request
* @throws AuthorizationException if there is any problem with the REST API authorization (access token)
* @throws ResourceNotFoundException if the resource cannot be found
* @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
* @throws SmartsheetException if there is any other error during the operation
*/
public Sheet createSheetInWorkspace(long workspaceId, Sheet sheet) throws SmartsheetException;
/**
* Create a sheet (from existing sheet or template) in given workspace.
*
* It mirrors to the following Smartsheet REST API method: POST /workspaces/{workspaceId}/sheets
*
* @param workspaceId the workspace id
* @param sheet the sheet to create
* @param includes used to specify the optional objects to include
* @return the created sheet
* @throws IllegalArgumentException if any argument is null or empty string
* @throws InvalidRequestException if there is any problem with the REST API request
* @throws AuthorizationException if there is any problem with the REST API authorization (access token)
* @throws ResourceNotFoundException if the resource cannot be found
* @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
* @throws SmartsheetException if there is any other error during the operation
*/
public Sheet createSheetInWorkspaceFromTemplate(long workspaceId, Sheet sheet, EnumSet includes) throws SmartsheetException;
/**
* Delete a sheet.
*
* It mirrors to the following Smartsheet REST API method: DELETE /sheet{id}
*
* Parameters: - id : the ID of the sheet
*
* Returns: None
*
*
* @param id the id
* @throws IllegalArgumentException if any argument is null or empty string
* @throws InvalidRequestException if there is any problem with the REST API request
* @throws AuthorizationException if there is any problem with the REST API authorization (access token)
* @throws ResourceNotFoundException if the resource cannot be found
* @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
* @throws SmartsheetException if there is any other error during the operation
*/
public void deleteSheet(long id) throws SmartsheetException;
/**
* Update a sheet.
*
* It mirrors to the following Smartsheet REST API method: PUT /sheet/{id}
*
* @param sheet the sheet to update
* @return the updated sheet
* @throws IllegalArgumentException if any argument is null or empty string
* @throws InvalidRequestException if there is any problem with the REST API request
* @throws AuthorizationException if there is any problem with the REST API authorization (access token)
* @throws ResourceNotFoundException if the resource cannot be found
* @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
* @throws SmartsheetException if there is any other error during the operation
*/
public Sheet updateSheet(Sheet sheet) throws SmartsheetException;
/**
* Get a sheet version.
*
* It mirrors to the following Smartsheet REST API method: GET /sheet/{id}/version
*
* @param id the id
* @return the sheet version (note that if there is no such resource, this method will throw
* ResourceNotFoundException)
* @throws IllegalArgumentException if any argument is null or empty string
* @throws InvalidRequestException if there is any problem with the REST API request
* @throws AuthorizationException if there is any problem with the REST API authorization (access token)
* @throws ResourceNotFoundException if the resource cannot be found
* @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
* @throws SmartsheetException if there is any other error during the operation
*/
public int getSheetVersion(long id) throws SmartsheetException;
/**
* Send a sheet as a PDF attachment via email to the designated recipients.
*
* It mirrors to the following Smartsheet REST API method: POST /sheet/{sheetId}/emails
*
* @param id the id
* @param email the email
* @throws IllegalArgumentException if any argument is null or empty string
* @throws InvalidRequestException if there is any problem with the REST API request
* @throws AuthorizationException if there is any problem with the REST API authorization (access token)
* @throws ResourceNotFoundException if the resource cannot be found
* @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
* @throws SmartsheetException if there is any other error during the operation
*/
public void sendSheet(long id, SheetEmail email) throws SmartsheetException;
/**
* Return the ShareResources object that provides access to Share resources associated with Sheet resources.
*
* @return the share resources object
*/
public ShareResources shareResources();
/**
* Return the SheetRowResources object that provides access to Row resources associated with Sheet resources.
*
* @return the sheet row resources
*/
public SheetRowResources rowResources();
/**
* Return the SheetColumnResources object that provides access to Column resources associated with Sheet resources.
*
* @return the sheet column resources
*/
public SheetColumnResources columnResources();
/**
* Return the AttachmentResources object that provides access to attachment resources associated with
* Sheet resources.
*
* @return the associated attachment resources
*/
public SheetAttachmentResources attachmentResources();
/**
* Return the SheetDiscussionResources object that provides access to discussion resources associated with
* Sheet resources.
*
* @return the associated discussion resources
*/
public SheetDiscussionResources discussionResources();
/**
* Return the SheetCommentResources object that provides access to discussion resources associated with
* Sheet resources.
*
* @return the associated comment resources
*/
public SheetCommentResources commentResources();
/**
* Return the SheetUpdateRequestResources object that provides access to update request resources
* associated with Sheet resources.
*
* @return the associated update request resources
*/
public SheetUpdateRequestResources updateRequestResources();
/**
* Get the status of the Publish settings of the sheet, including the URLs of any enabled publishings.
*
* It mirrors to the following Smartsheet REST API method: GET /sheet/{sheetId}/publish
*
* @param id the id
* @return the publish status (note that if there is no such resource, this method will throw ResourceNotFoundException rather than returning null)
* @throws IllegalArgumentException if any argument is null or empty string
* @throws InvalidRequestException if there is any problem with the REST API request
* @throws AuthorizationException if there is any problem with the REST API authorization (access token)
* @throws ResourceNotFoundException if the resource cannot be found
* @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
* @throws SmartsheetException if there is any other error during the operation
*/
public SheetPublish getPublishStatus(long id) throws SmartsheetException;
/**
* Sets the publish status of a sheet and returns the new status, including the URLs of any enabled publishings.
*
* It mirrors to the following Smartsheet REST API method: PUT /sheet/{sheetId}/publish
*
* @param id the id
* @param publish the SheetPublish object limited.
* @return the update SheetPublish object (note that if there is no such resource, this method will throw a
* ResourceNotFoundException rather than returning null).
* @throws IllegalArgumentException if any argument is null or empty string
* @throws InvalidRequestException if there is any problem with the REST API request
* @throws AuthorizationException if there is any problem with the REST API authorization (access token)
* @throws ResourceNotFoundException if the resource cannot be found
* @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
* @throws SmartsheetException if there is any other error during the operation
*/
public SheetPublish updatePublishStatus(long id, SheetPublish publish) throws SmartsheetException;
/**
* Creates a copy of the specified sheet.
*
* It mirrors to the following Smartsheet REST API method: POST /folders/{folderId}/copy
*
* Exceptions:
* IllegalArgumentException : if folder is null
* InvalidRequestException : if there is any problem with the REST API request
* AuthorizationException : if there is any problem with the REST API authorization(access token)
* ServiceUnavailableException : if the REST API service is not available (possibly due to rate limiting)
* SmartsheetRestException : if there is any other REST API related error occurred during the operation
* SmartsheetException : if there is any other error occurred during the operation
*
* @param sheetId the sheet id
* @param containerDestination describes the destination container
* @param includes optional parameters to include
* @return the sheet
* @throws SmartsheetException the smartsheet exception
*/
public Sheet copySheet(long sheetId, ContainerDestination containerDestination, EnumSet includes) throws SmartsheetException;
/**
* Moves the specified Sheet to another location.
*
* It mirrors to the following Smartsheet REST API method: POST /folders/{folderId}/move
*
* Exceptions:
* IllegalArgumentException : if folder is null
* InvalidRequestException : if there is any problem with the REST API request
* AuthorizationException : if there is any problem with the REST API authorization(access token)
* ServiceUnavailableException : if the REST API service is not available (possibly due to rate limiting)
* SmartsheetRestException : if there is any other REST API related error occurred during the operation
* SmartsheetException : if there is any other error occurred during the operation
*
* @param sheetId the folder id
* @param containerDestination describes the destination container
* @return the sheet
* @throws SmartsheetException the smartsheet exception
*/
public Sheet moveSheet(long sheetId, ContainerDestination containerDestination) throws SmartsheetException;
/**
* Creates an Update Request for the specified Row(s) within the Sheet.
*
* It mirrors to the following Smartsheet REST API method: POST /sheets/{sheetId}/updaterequests
*
* Exceptions:
* - IllegalArgumentException : if any argument is null
* - InvalidRequestException : if there is any problem with the REST API request
* - AuthorizationException : if there is any problem with the REST API authorization(access token)
* - ServiceUnavailableException : if the REST API service is not available (possibly due to rate limiting)
* - SmartsheetRestException : if there is any other REST API related error occurred during the operation
* - SmartsheetException : if there is any other error occurred during the operation
*
* @param sheetId the sheet id
* @param email the email
* @return the update request object
* @throws SmartsheetException the smartsheet exception
*/
@Deprecated
public UpdateRequest createUpdateRequest(long sheetId, MultiRowEmail email) throws SmartsheetException;
}