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
020import com.unboundid.scim.data.BaseResource;
021import com.unboundid.scim.data.BulkConfig;
022import com.unboundid.scim.data.ResourceFactory;
023import com.unboundid.scim.schema.ResourceDescriptor;
024import com.unboundid.scim.sdk.BulkContentHandler;
025import com.unboundid.scim.sdk.InvalidResourceException;
026import com.unboundid.scim.sdk.Resources;
027import com.unboundid.scim.sdk.SCIMException;
028
029import java.io.File;
030import java.io.InputStream;
031
032
033
034/**
035 * This interface provides methods that may be used to read SCIM objects
036 * from their external representation. There are un-marshaller implementations
037 * for XML and JSON. Un-marshaller implementations are required to be
038 * thread-safe.
039 */
040public interface Unmarshaller {
041
042  /**
043   * Reads a SCIM resource from an input stream.
044   *
045   * @param <R> The type of resource instance.
046   * @param inputStream  The input stream containing the SCIM object to be read.
047   * @param resourceDescriptor The descriptor of the SCIM resource to be read.
048   * @param resourceFactory The resource factory to use to create the resource
049   *                        instance.
050   *
051   * @return  The SCIM resource that was read.
052   *
053   * @throws InvalidResourceException If an error occurred.
054   */
055  <R extends BaseResource> R unmarshal(
056      final InputStream inputStream,
057      final ResourceDescriptor resourceDescriptor,
058      final ResourceFactory<R> resourceFactory)
059      throws InvalidResourceException;
060
061  /**
062   * Reads a SCIM query response from an input stream.
063   *
064   * @param <R> The type of resource instance.
065   * @param inputStream  The input stream containing the SCIM object to be read.
066   * @param resourceDescriptor The descriptor of the SCIM resource to be read.
067   * @param resourceFactory The resource factory to use to create the resource
068   *                        instance.
069   *
070   * @return The SCIM query response that was read.
071   *
072   * @throws InvalidResourceException If an error occurred.
073   */
074  <R extends BaseResource> Resources<R> unmarshalResources(
075      final InputStream inputStream,
076      final ResourceDescriptor resourceDescriptor,
077      final ResourceFactory<R> resourceFactory)
078      throws InvalidResourceException;
079
080  /**
081   * Reads a SCIM error response from an input stream.
082   *
083   * @param inputStream  The input stream containing the SCIM object to be read.
084   * @return The SCIM error response that was read.
085   *
086   * @throws InvalidResourceException If an error occurred.
087   */
088  SCIMException unmarshalError(final InputStream inputStream)
089      throws InvalidResourceException;
090
091  /**
092   * Reads a SCIM bulk request or response from an input stream.
093   *
094   * @param inputStream  The input stream containing the bulk content to be
095   *                     read.
096   * @param bulkConfig   The bulk configuration settings to be enforced.
097   * @param handler      A bulk operation listener to handle the content as it
098   *                     is read.
099   *
100   * @throws SCIMException If the bulk content could not be read.
101   */
102  void bulkUnmarshal(final InputStream inputStream,
103                     final BulkConfig bulkConfig,
104                     final BulkContentHandler handler)
105      throws SCIMException;
106
107
108
109  /**
110   * Reads a SCIM bulk request or response from a file.
111   *
112   * @param file         The file containing the bulk content to be read.
113   * @param bulkConfig   The bulk configuration settings to be enforced.
114   * @param handler      A bulk operation listener to handle the content as it
115   *                     is read.
116   *
117   * @throws SCIMException If the bulk content could not be read.
118   */
119  void bulkUnmarshal(final File file,
120                     final BulkConfig bulkConfig,
121                     final BulkContentHandler handler)
122      throws SCIMException;
123}