com.podio.comment.CommentAPI Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of api Show documentation
The official Java wrapper for the Podio API
There is a newer version: 0.7.9
package com.podio.comment;

import java.util.List;

import javax.ws.rs.core.MediaType;

import com.podio.BaseAPI;
import com.podio.ResourceFactory;
import com.podio.common.Reference;
import com.sun.jersey.api.client.GenericType;

/**
 * Comments are made by users on different objects. Objects can f.ex. be items,
 * status, etc. Comments is simply a text that can be any length.
 * 
 * Comments are made from the API of the object, see f.ex. Items for more
 * details. Comments are however updated and deleted from the comment API.
 */
public class CommentAPI extends BaseAPI {

	public CommentAPI(ResourceFactory resourceFactory) {
		super(resourceFactory);
	}

	/**
	 * Used to retrieve all the comments that have been made on an object of the
	 * given type and with the given id. It returns a list of all the comments
	 * sorted in ascending order by time created.
	 * 
	 * @param reference
	 *            The reference to the object from which the comments should be
	 *            retrieved
	 * @return The comments on the object
	 */
	public List getComments(Reference reference) {
		return getResourceFactory().getApiResource(
				"/comment/" + reference.getType() + "/" + reference.getId())
				.get(new GenericType>() {
				});
	}

	/**
	 * Returns the contents of a comment. It is not possible to see where the
	 * comment was made, only the comment itself.
	 * 
	 * @param commentId
	 *            The id of the comment
	 * @return The comment
	 */
	public Comment getComment(int commentId) {
		return getResourceFactory().getApiResource("/comment/" + commentId)
				.get(Comment.class);
	}

	/**
	 * Adds a new comment to the object of the given type and id, f.ex. item 1.
	 * 
	 * @param reference
	 *            The reference to the object the comment should be added to
	 * @param comment
	 *            The comment that should be added
	 * @param silent
	 *            True if the update should be silent, false otherwise
	 */
	public int addComment(Reference reference, CommentCreate comment,
			boolean silent) {
		return getResourceFactory()
				.getApiResource(
						"/comment/" + reference.getType() + "/"
								+ reference.getId())
				.queryParam("silent", silent ? "1" : "0")
				.entity(comment, MediaType.APPLICATION_JSON_TYPE)
				.post(CommentCreateResponse.class).getId();
	}

	/**
	 * Updates an already created comment. This should only be used to correct
	 * spelling and grammatical mistakes in the comment.
	 * 
	 * @param commentId
	 *            The id of the comment
	 * @param comment
	 *            The updated comment definition
	 */
	public void updateComment(int commentId, CommentUpdate comment) {
		getResourceFactory().getApiResource("/comment/" + commentId)
				.entity(comment, MediaType.APPLICATION_JSON_TYPE).put();
	}

	/**
	 * Deletes a comment made by a user. This can be used to retract a comment
	 * that was made and which the user regrets.
	 * 
	 * @param commentId
	 *            The id of the comment
	 */
	public void deleteComment(int commentId) {
		getResourceFactory().getApiResource("/comment/" + commentId).delete();
	}
}