001/*
002 * Copyright 2011-2013 UnboundID Corp.
003 *
004 * This program is free software; you can redistribute it and/or modify
005 * it under the terms of the GNU General Public License (GPLv2 only)
006 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
007 * as published by the Free Software Foundation.
008 *
009 * This program is distributed in the hope that it will be useful,
010 * but WITHOUT ANY WARRANTY; without even the implied warranty of
011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
012 * GNU General Public License for more details.
013 *
014 * You should have received a copy of the GNU General Public License
015 * along with this program; if not, see <http://www.gnu.org/licenses>.
016 */
017
018package com.unboundid.scim.marshal;
019
020
021import com.unboundid.scim.data.BaseResource;
022import com.unboundid.scim.sdk.BulkOperation;
023import com.unboundid.scim.sdk.Resources;
024import com.unboundid.scim.sdk.SCIMException;
025
026import java.io.OutputStream;
027import java.util.List;
028
029
030
031/**
032 * This interface provides methods that may be used to write SCIM objects
033 * to an external representation. There are marshaller implementations
034 * for XML and JSON. Marshaller implementations are required to be thread-safe.
035 */
036public interface Marshaller
037{
038  /**
039   * Write a SCIM object to an output stream.
040   *
041   * @param resource      The SCIM resource to be written.
042   * @param outputStream  The output stream to which the SCIM object should
043   *                      be written.
044   *
045   * @throws SCIMException  If the data could not be written.
046   */
047  void marshal(BaseResource resource, OutputStream outputStream)
048    throws SCIMException;
049
050  /**
051   * Write a SCIM listing response to an output stream.
052   *
053   * @param response      The SCIM response to be written.
054   * @param outputStream  The output stream to which the SCIM response should
055   *                      be written.
056   *
057   * @throws SCIMException  If the data could not be written.
058   */
059  void marshal(Resources<? extends BaseResource> response,
060               OutputStream outputStream)
061    throws SCIMException;
062
063  /**
064   * Write a SCIM error response to an output stream.
065   *
066   * @param response      The SCIM response to be written.
067   * @param outputStream  The output stream to which the SCIM response should
068   *                      be written.
069   *
070   * @throws SCIMException  If the data could not be written.
071   */
072  void marshal(SCIMException response, OutputStream outputStream)
073    throws SCIMException;
074
075  /**
076   * Write the content of a SCIM bulk operation request or response to an
077   * output stream.
078   *
079   * @param outputStream  The output stream to which the content should be
080   *                      written.
081   * @param failOnErrors  The value of failOnErrors, or -1 to not provide a
082   *                      value.
083   * @param operations    The bulk operations to include in the content.
084   *
085   * @throws SCIMException  If the data could not be written.
086   */
087  void bulkMarshal(OutputStream outputStream, int failOnErrors,
088                   List<BulkOperation> operations)
089    throws SCIMException;
090}