001/*
002 * Copyright 2011-2016 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  /**
065   * Write a SCIM error response to an output stream.
066   *
067   * @param response      The SCIM response to be written.
068   * @param outputStream  The output stream to which the SCIM response should
069   *                      be written.
070   *
071   * @throws SCIMException  If the data could not be written.
072   */
073  void marshal(SCIMException response, OutputStream outputStream)
074    throws SCIMException;
075
076  /**
077   * Write the content of a SCIM bulk operation request or response to an
078   * output stream.
079   *
080   * @param outputStream  The output stream to which the content should be
081   *                      written.
082   * @param failOnErrors  The value of failOnErrors, or -1 to not provide a
083   *                      value.
084   * @param operations    The bulk operations to include in the content.
085   *
086   * @throws SCIMException  If the data could not be written.
087   */
088  void bulkMarshal(OutputStream outputStream, int failOnErrors,
089                   List<BulkOperation> operations)
090    throws SCIMException;
091}