com.constantcontact.services.contacts.IContactService Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of constantcontact Show documentation
Constant Contact Java SDK
The newest version!
package com.constantcontact.services.contacts;

import com.constantcontact.components.contacts.Contact;
import com.constantcontact.components.generic.response.Pagination;
import com.constantcontact.components.generic.response.ResultSet;
import com.constantcontact.exceptions.service.ConstantContactServiceException;
import com.constantcontact.services.base.IBaseService;

/**
 * Interface for {@link ContactService} class in Constant Contact.
 *
 * @author ConstantContact
 */
public interface IContactService extends IBaseService {

  /**
   * Implements the get Contacts operation of the Contacts API by calling the ConstantContact server side.
   *
   * @param limit                  Limit.
   * @param modifiedSinceTimestamp This time stamp is an ISO-8601 ordinal date supporting offset. 

   *                               It will return only the contacts modified since the supplied date. 

   *                               If you want to bypass this filter set modifiedSinceTimestamp to null.
   * @param status                 The status of contacts to return.
   *
   * @return A {@link ResultSet} of {@link Contact} containing data as returned by the server on success; 

   * An exception is thrown otherwise.
   *
   * @throws ConstantContactServiceException When something went wrong in the Constant Contact flow or an error is returned from server.
   */
  ResultSet getContacts(Integer limit, String modifiedSinceTimestamp, Contact.Status status) throws ConstantContactServiceException;

  /**
   * Implements the get Contacts operation of the Contacts API by calling the ConstantContact server side.
   *
   * @param pagination A {@link Pagination} instance containing the link to the next page of results.
   *                   An exception is thrown otherwise.
   *
   * @throws ConstantContactServiceException When something went wrong in the Constant Contact flow or an error is returned from server.
   */
  ResultSet getContacts(Pagination pagination) throws ConstantContactServiceException;

  /**
   * Implements the get Contact operation of the Contacts API by calling the ConstantContact server side.
   *
   * @param contactId Unique contact id.
   *
   * @return Returns a {@link Contact} containing data as returned by the server on success; 

   * An exception is thrown otherwise.
   *
   * @throws ConstantContactServiceException When something went wrong in the Constant Contact flow or an error is returned from server.
   */
  Contact getContact(String contactId) throws ConstantContactServiceException;

  /**
   * Implements the get Contact By Email operation of the Contacts API by calling the ConstantContact server side.
   *
   * @param email Contact email address to search for.
   *
   * @return Returns a {@link ResultSet} of {@link Contact} containing data as returned by the server on success; 

   * An exception is thrown otherwise.
   *
   * @throws ConstantContactServiceException When something went wrong in the Constant Contact flow or an error is returned from server.
   */
  ResultSet getContactByEmail(String email) throws ConstantContactServiceException;

  /**
   * Implements the add Contact operation of the Contacts API by calling the ConstantContact server side.
   *
   * @param contact {@link Contact} to add.
   *
   * @return Returns the newly created {@link Contact} containing data as returned by the server on success; 

   * An exception is thrown otherwise.
   *
   * @throws ConstantContactServiceException When something went wrong in the Constant Contact flow or an error is returned from server.
   */
  Contact addContact(Contact contact, Boolean actionByVisitor) throws ConstantContactServiceException;

  /**
   * Implements the delete Contact operation of the Contacts API by calling the ConstantContact server side.
   *
   * @param contactId Unique contact id of the contact to delete.
   *
   * @return Returns true if operation succeeded; an exception is thrown otherwise.
   *
   * @throws ConstantContactServiceException When something went wrong in the Constant Contact flow or an error is returned from server.
   */
  boolean deleteContact(String contactId) throws ConstantContactServiceException;

  /**
   * Implements the delete Contact From Lists (all lists) operation of the Contacts API by calling the ConstantContact server side.
   *
   * @param contactId Contact id to be removed from all the lists.
   *
   * @return Returns true if operation succeeded; an exception is thrown otherwise.
   *
   * @throws ConstantContactServiceException When something went wrong in the Constant Contact flow or an error is returned from server.
   */
  boolean deleteContactFromLists(String contactId) throws ConstantContactServiceException;

  /**
   * Implements the delete Contact From List (a specific list) operation of the Contacts API by calling the ConstantContact server side.
   *
   * @param contactId Contact id to be removed.
   * @param listId    ContactList to remove the contact from.
   *
   * @return Returns true if operation succeeded; an exception is thrown otherwise.
   *
   * @throws ConstantContactServiceException When something went wrong in the Constant Contact flow or an error is returned from server.
   */
  boolean deleteContactFromList(String contactId, String listId) throws ConstantContactServiceException;

  /**
   * Implements the update Contact operation of the Contacts API by calling the ConstantContact server side.

   * A specific contact is identified by its internal id.
   *
   * @param contact {@link Contact} to be updated.
   *
   * @return Returns the updated {@link Contact} containing data as returned by the server on success; 

   * An exception is thrown otherwise.
   *
   * @throws ConstantContactServiceException When something went wrong in the Constant Contact flow or an error is returned from server.
   */
  Contact updateContact(Contact contact, Boolean actionByVisitor) throws ConstantContactServiceException;
}