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 import com.unboundid.scim.data.BaseResource;
021 import com.unboundid.scim.data.BulkConfig;
022 import com.unboundid.scim.data.ResourceFactory;
023 import com.unboundid.scim.schema.ResourceDescriptor;
024 import com.unboundid.scim.sdk.BulkContentHandler;
025 import com.unboundid.scim.sdk.InvalidResourceException;
026 import com.unboundid.scim.sdk.Resources;
027 import com.unboundid.scim.sdk.SCIMException;
028
029 import java.io.File;
030 import 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 */
040 public 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 }