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
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  /**
082   * Reads a SCIM error response from an input stream.
083   *
084   * @param inputStream  The input stream containing the SCIM object to be read.
085   * @return The SCIM error response that was read.
086   *
087   * @throws InvalidResourceException If an error occurred.
088   */
089  SCIMException unmarshalError(final InputStream inputStream)
090      throws InvalidResourceException;
091
092  /**
093   * Reads a SCIM bulk request or response from an input stream.
094   *
095   * @param inputStream  The input stream containing the bulk content to be
096   *                     read.
097   * @param bulkConfig   The bulk configuration settings to be enforced.
098   * @param handler      A bulk operation listener to handle the content as it
099   *                     is read.
100   *
101   * @throws SCIMException If the bulk content could not be read.
102   */
103  void bulkUnmarshal(final InputStream inputStream,
104                     final BulkConfig bulkConfig,
105                     final BulkContentHandler handler)
106      throws SCIMException;
107
108
109
110  /**
111   * Reads a SCIM bulk request or response from a file.
112   *
113   * @param file         The file containing the bulk content to be read.
114   * @param bulkConfig   The bulk configuration settings to be enforced.
115   * @param handler      A bulk operation listener to handle the content as it
116   *                     is read.
117   *
118   * @throws SCIMException If the bulk content could not be read.
119   */
120  void bulkUnmarshal(final File file,
121                     final BulkConfig bulkConfig,
122                     final BulkContentHandler handler)
123      throws SCIMException;
124}