001/*
002 * Portions of this software was developed by employees of the National Institute
003 * of Standards and Technology (NIST), an agency of the Federal Government and is
004 * being made available as a public service. Pursuant to title 17 United States
005 * Code Section 105, works of NIST employees are not subject to copyright
006 * protection in the United States. This software may be subject to foreign
007 * copyright. Permission in the United States and in foreign countries, to the
008 * extent that NIST may hold copyright, to use, copy, modify, create derivative
009 * works, and distribute this software and its documentation without fee is hereby
010 * granted on a non-exclusive basis, provided that this notice and disclaimer
011 * of warranty appears in all copies.
012 *
013 * THE SOFTWARE IS PROVIDED 'AS IS' WITHOUT ANY WARRANTY OF ANY KIND, EITHER
014 * EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, ANY WARRANTY
015 * THAT THE SOFTWARE WILL CONFORM TO SPECIFICATIONS, ANY IMPLIED WARRANTIES OF
016 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND FREEDOM FROM
017 * INFRINGEMENT, AND ANY WARRANTY THAT THE DOCUMENTATION WILL CONFORM TO THE
018 * SOFTWARE, OR ANY WARRANTY THAT THE SOFTWARE WILL BE ERROR FREE.  IN NO EVENT
019 * SHALL NIST BE LIABLE FOR ANY DAMAGES, INCLUDING, BUT NOT LIMITED TO, DIRECT,
020 * INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES, ARISING OUT OF, RESULTING FROM,
021 * OR IN ANY WAY CONNECTED WITH THIS SOFTWARE, WHETHER OR NOT BASED UPON WARRANTY,
022 * CONTRACT, TORT, OR OTHERWISE, WHETHER OR NOT INJURY WAS SUSTAINED BY PERSONS OR
023 * PROPERTY OR OTHERWISE, AND WHETHER OR NOT LOSS WAS SUSTAINED FROM, OR AROSE OUT
024 * OF THE RESULTS OF, OR USE OF, THE SOFTWARE OR SERVICES PROVIDED HEREUNDER.
025 */
026
027package gov.nist.secauto.metaschema.databind.io;
028
029import gov.nist.secauto.metaschema.core.configuration.IConfiguration;
030import gov.nist.secauto.metaschema.core.configuration.IMutableConfiguration;
031import gov.nist.secauto.metaschema.core.metapath.item.node.INodeItem;
032import gov.nist.secauto.metaschema.core.model.constraint.IConstraintValidationHandler;
033import gov.nist.secauto.metaschema.core.util.ObjectUtils;
034
035import java.io.File;
036import java.io.IOException;
037import java.io.InputStream;
038import java.io.InputStreamReader;
039import java.io.Reader;
040import java.net.URI;
041import java.net.URISyntaxException;
042import java.net.URL;
043import java.nio.charset.StandardCharsets;
044import java.nio.file.Files;
045import java.nio.file.Path;
046
047import edu.umd.cs.findbugs.annotations.NonNull;
048
049/**
050 * Implementations of this interface are able to read structured data into a
051 * bound object instance of the parameterized type.
052 *
053 * @param <CLASS>
054 *          the Java type into which data can be read
055 */
056public interface IDeserializer<CLASS> extends IMutableConfiguration<DeserializationFeature<?>> {
057
058  @Override
059  IDeserializer<CLASS> enableFeature(DeserializationFeature<?> feature);
060
061  @Override
062  IDeserializer<CLASS> disableFeature(DeserializationFeature<?> feature);
063
064  @Override
065  IDeserializer<CLASS> applyConfiguration(IConfiguration<DeserializationFeature<?>> other);
066
067  @Override
068  IDeserializer<CLASS> set(DeserializationFeature<?> feature, Object value);
069
070  /**
071   * Determine if the serializer is performing validation.
072   *
073   * @return {@code true} if the serializer is performing content validation, or
074   *         {@code false} otherwise
075   */
076  default boolean isValidating() {
077    return isFeatureEnabled(DeserializationFeature.DESERIALIZE_VALIDATE_CONSTRAINTS);
078  }
079
080  /**
081   * Get the constraint validation handler configured for this deserializer, which
082   * will be used to validate loaded data.
083   *
084   * @return the validation handler
085   */
086  @NonNull
087  IConstraintValidationHandler getConstraintValidationHandler();
088
089  /**
090   * Set the constraint violation handler for constraint validation.
091   *
092   * @param handler
093   *          the handler to use
094   */
095  void setConstraintValidationHandler(@NonNull IConstraintValidationHandler handler);
096
097  /**
098   * Read data from the {@link InputStream} into a bound class instance.
099   *
100   * @param is
101   *          the input stream to read from
102   * @param documentUri
103   *          the URI of the document to read from
104   * @return the instance data
105   * @throws IOException
106   *           if an error occurred while reading data from the stream
107   */
108  @NonNull
109  default CLASS deserialize(@NonNull InputStream is, @NonNull URI documentUri) throws IOException {
110    return deserialize(new InputStreamReader(is, StandardCharsets.UTF_8), documentUri);
111  }
112
113  /**
114   * Read data from the {@link Path} into a bound class instance.
115   *
116   * @param path
117   *          the file to read from
118   * @return the instance data
119   * @throws IOException
120   *           if an error occurred while writing data to the file indicated by
121   *           the {@code path} parameter
122   */
123  @NonNull
124  default CLASS deserialize(@NonNull Path path) throws IOException {
125    try (Reader reader = ObjectUtils.notNull(Files.newBufferedReader(path, StandardCharsets.UTF_8))) {
126      return deserialize(reader, ObjectUtils.notNull(path.toUri()));
127    }
128  }
129
130  /**
131   * Read data from the {@link File} into a bound class instance.
132   *
133   * @param file
134   *          the file to read from
135   * @return the instance data
136   * @throws IOException
137   *           if an error occurred while reading data from the stream
138   */
139  @NonNull
140  default CLASS deserialize(@NonNull File file) throws IOException {
141    return deserialize(ObjectUtils.notNull(file.toPath()));
142  }
143
144  /**
145   * Read data from the remote resource into a bound class instance.
146   *
147   *
148   * @param url
149   *          the remote resource to read from
150   * @return the instance data
151   * @throws IOException
152   *           if an error occurred while reading data from the stream
153   * @throws URISyntaxException
154   *           if the provided URL is not formatted strictly according to to
155   *           RFC2396 and cannot be converted to a URI.
156   */
157  @NonNull
158  default CLASS deserialize(@NonNull URL url) throws IOException, URISyntaxException {
159    try (InputStream in = ObjectUtils.notNull(url.openStream())) {
160      return deserialize(in, ObjectUtils.notNull(url.toURI()));
161    }
162  }
163
164  /**
165   * Read data from the {@link Reader} into a bound class instance.
166   *
167   *
168   * @param reader
169   *          the reader to read from
170   * @param documentUri
171   *          the URI of the document to read from
172   * @return the instance data
173   * @throws IOException
174   *           if an error occurred while reading data from the stream
175   */
176  @NonNull
177  default CLASS deserialize(@NonNull Reader reader, @NonNull URI documentUri) throws IOException {
178    return deserializeToValue(reader, documentUri);
179  }
180
181  /**
182   * Read data from the {@link Reader} into a node item instance.
183   *
184   * @param is
185   *          the input stream to read from
186   * @param documentUri
187   *          the URI of the document to read from
188   * @return a new node item
189   * @throws IOException
190   *           if an error occurred while reading data from the stream
191   */
192  @NonNull
193  default INodeItem deserializeToNodeItem(@NonNull InputStream is, @NonNull URI documentUri)
194      throws IOException {
195    return deserializeToNodeItem(new InputStreamReader(is, StandardCharsets.UTF_8), documentUri);
196  }
197
198  /**
199   * Read data from the {@link Reader} into a node item instance.
200   *
201   * @param reader
202   *          the reader to read from
203   * @param documentUri
204   *          the URI of the document to read from
205   * @return a new node item
206   * @throws IOException
207   *           if an error occurred while reading data from the stream
208   */
209  @NonNull
210  INodeItem deserializeToNodeItem(@NonNull Reader reader, @NonNull URI documentUri) throws IOException;
211
212  /**
213   * Read data from the {@link Reader} into a node item instance.
214   *
215   * @param reader
216   *          the reader to read from
217   * @param documentUri
218   *          the URI of the document to read from
219   * @return a new node item
220   * @throws IOException
221   *           if an error occurred while reading data from the stream
222   */
223  @NonNull
224  CLASS deserializeToValue(@NonNull Reader reader, @NonNull URI documentUri) throws IOException;
225}