001    /*
002     * Copyright 2011-2012 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    
018    package com.unboundid.scim.marshal;
019    
020    
021    import com.unboundid.scim.data.BaseResource;
022    import com.unboundid.scim.sdk.BulkOperation;
023    import com.unboundid.scim.sdk.Resources;
024    import com.unboundid.scim.sdk.SCIMException;
025    
026    import java.io.OutputStream;
027    import 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     */
036    public 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    }