001/*
002 * Copyright 2012-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
018/*
019 * Copyright 2011-2016 UnboundID Corp.
020 *
021 * This program is free software; you can redistribute it and/or modify
022 * it under the terms of the GNU General Public License (GPLv2 only)
023 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
024 * as published by the Free Software Foundation.
025 *
026 * This program is distributed in the hope that it will be useful,
027 * but WITHOUT ANY WARRANTY; without even the implied warranty of
028 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
029 * GNU General Public License for more details.
030 *
031 * You should have received a copy of the GNU General Public License
032 * along with this program; if not, see <http://www.gnu.org/licenses>.
033 */
034
035package com.unboundid.scim.marshal;
036
037
038import com.unboundid.scim.data.BaseResource;
039import com.unboundid.scim.sdk.BulkOperation;
040import com.unboundid.scim.sdk.Resources;
041import com.unboundid.scim.sdk.SCIMException;
042
043import java.util.List;
044import java.util.Set;
045
046
047
048/**
049 * This interface provides methods that may be used to write a stream of
050 * SCIM objects to an external representation. There are stream marshaller
051 * implementations for XML and JSON. Stream marshaller implementations are
052 * not required to be thread-safe.
053 */
054public interface StreamMarshaller
055{
056  /**
057   * Write a SCIM object.
058   *
059   * @param resource      The SCIM resource to be written.
060   *
061   * @throws SCIMException  If the data could not be written.
062   */
063  void marshal(BaseResource resource)
064    throws SCIMException;
065
066  /**
067   * Write a SCIM query response.
068   *
069   * @param response      The SCIM response to be written.
070   *
071   * @throws SCIMException  If the data could not be written.
072   */
073  void marshal(Resources<? extends BaseResource> response)
074    throws SCIMException;
075
076  /**
077   * Write a SCIM error response.
078   *
079   * @param response      The SCIM response to be written.
080   *
081   * @throws SCIMException  If the data could not be written.
082   */
083  void marshal(SCIMException response)
084    throws SCIMException;
085
086  /**
087   * Write the content of a SCIM bulk operation request or response.
088   *
089   * @param failOnErrors  The value of failOnErrors, or -1 to not provide a
090   *                      value.
091   * @param operations    The bulk operations to include in the content.
092   *
093   * @throws SCIMException  If the data could not be written.
094   */
095  void bulkMarshal(int failOnErrors,
096                   List<BulkOperation> operations)
097    throws SCIMException;
098
099
100
101  /**
102   * Write the start of a bulk request or response.
103   *
104   * @param failOnErrors  The value of failOnErrors, or -1 to not provide a
105   *                      value.
106   * @param schemaURIs    The set of schema URIs used by the bulk request or
107   *                      response.
108   *
109   * @throws SCIMException  If the data could not be written.
110   */
111  void writeBulkStart(final int failOnErrors,
112                      final Set<String> schemaURIs)
113      throws SCIMException;
114
115
116
117  /**
118   * Write a bulk operation to a bulk request or response.
119   *
120   * @param o  The bulk operation to write.
121   *
122   * @throws SCIMException  If the data could not be written.
123   */
124  void writeBulkOperation(final BulkOperation o)
125      throws SCIMException;
126
127
128
129  /**
130   * Write the end of a bulk request or response.
131   *
132   * @throws SCIMException  If the data could not be written.
133   */
134  void writeBulkFinish()
135      throws SCIMException;
136
137
138
139  /**
140   * Close the marshaller.
141   *
142   * @throws SCIMException  If the data could not be written.
143   */
144  void close()
145      throws SCIMException;
146}