001/*
002 * SPDX-FileCopyrightText: none
003 * SPDX-License-Identifier: CC0-1.0
004 */
005
006package gov.nist.secauto.metaschema.databind.io;
007
008import gov.nist.secauto.metaschema.core.configuration.IConfiguration;
009import gov.nist.secauto.metaschema.core.configuration.IMutableConfiguration;
010import gov.nist.secauto.metaschema.core.metapath.item.node.INodeItem;
011import gov.nist.secauto.metaschema.core.model.IBoundObject;
012import gov.nist.secauto.metaschema.core.model.constraint.IConstraintValidationHandler;
013import gov.nist.secauto.metaschema.core.util.ObjectUtils;
014
015import java.io.File;
016import java.io.IOException;
017import java.io.InputStream;
018import java.io.InputStreamReader;
019import java.io.Reader;
020import java.net.URI;
021import java.net.URISyntaxException;
022import java.net.URL;
023import java.nio.charset.StandardCharsets;
024import java.nio.file.Files;
025import java.nio.file.Path;
026
027import edu.umd.cs.findbugs.annotations.NonNull;
028
029/**
030 * Implementations of this interface are able to read structured data into a
031 * bound object instance of the parameterized type.
032 *
033 * @param <CLASS>
034 *          the Java type into which data can be read
035 */
036public interface IDeserializer<CLASS extends IBoundObject> extends IMutableConfiguration<DeserializationFeature<?>> {
037
038  @Override
039  IDeserializer<CLASS> enableFeature(DeserializationFeature<?> feature);
040
041  @Override
042  IDeserializer<CLASS> disableFeature(DeserializationFeature<?> feature);
043
044  @Override
045  IDeserializer<CLASS> applyConfiguration(IConfiguration<DeserializationFeature<?>> other);
046
047  @Override
048  IDeserializer<CLASS> set(DeserializationFeature<?> feature, Object value);
049
050  /**
051   * Determine if the serializer is performing validation.
052   *
053   * @return {@code true} if the serializer is performing content validation, or
054   *         {@code false} otherwise
055   */
056  default boolean isValidating() {
057    return isFeatureEnabled(DeserializationFeature.DESERIALIZE_VALIDATE_CONSTRAINTS);
058  }
059
060  /**
061   * Get the constraint validation handler configured for this deserializer, which
062   * will be used to validate loaded data.
063   *
064   * @return the validation handler
065   */
066  @NonNull
067  IConstraintValidationHandler getConstraintValidationHandler();
068
069  /**
070   * Set the constraint violation handler for constraint validation.
071   *
072   * @param handler
073   *          the handler to use
074   */
075  void setConstraintValidationHandler(@NonNull IConstraintValidationHandler handler);
076
077  /**
078   * Read data from the {@link InputStream} into a bound class instance.
079   *
080   * @param is
081   *          the input stream to read from
082   * @param documentUri
083   *          the URI of the document to read from
084   * @return the instance data
085   * @throws IOException
086   *           if an error occurred while reading data from the stream
087   */
088  @NonNull
089  default CLASS deserialize(@NonNull InputStream is, @NonNull URI documentUri) throws IOException {
090    return deserialize(new InputStreamReader(is, StandardCharsets.UTF_8), documentUri);
091  }
092
093  /**
094   * Read data from the {@link Path} into a bound class instance.
095   *
096   * @param path
097   *          the file to read from
098   * @return the instance data
099   * @throws IOException
100   *           if an error occurred while writing data to the file indicated by
101   *           the {@code path} parameter
102   */
103  @NonNull
104  default CLASS deserialize(@NonNull Path path) throws IOException {
105    try (Reader reader = ObjectUtils.notNull(Files.newBufferedReader(path, StandardCharsets.UTF_8))) {
106      return deserialize(reader, ObjectUtils.notNull(path.toUri()));
107    }
108  }
109
110  /**
111   * Read data from the {@link File} into a bound class instance.
112   *
113   * @param file
114   *          the file to read from
115   * @return the instance data
116   * @throws IOException
117   *           if an error occurred while reading data from the stream
118   */
119  @NonNull
120  default CLASS deserialize(@NonNull File file) throws IOException {
121    return deserialize(ObjectUtils.notNull(file.toPath()));
122  }
123
124  /**
125   * Read data from the remote resource into a bound class instance.
126   *
127   *
128   * @param url
129   *          the remote resource to read from
130   * @return the instance data
131   * @throws IOException
132   *           if an error occurred while reading data from the stream
133   * @throws URISyntaxException
134   *           if the provided URL is not formatted strictly according to to
135   *           RFC2396 and cannot be converted to a URI.
136   */
137  @NonNull
138  default CLASS deserialize(@NonNull URL url) throws IOException, URISyntaxException {
139    try (InputStream in = ObjectUtils.notNull(url.openStream())) {
140      return deserialize(in, ObjectUtils.notNull(url.toURI()));
141    }
142  }
143
144  /**
145   * Read data from the {@link Reader} into a bound class instance.
146   *
147   *
148   * @param reader
149   *          the reader to read from
150   * @param documentUri
151   *          the URI of the document to read from
152   * @return the instance data
153   * @throws IOException
154   *           if an error occurred while reading data from the stream
155   */
156  @NonNull
157  default CLASS deserialize(@NonNull Reader reader, @NonNull URI documentUri) throws IOException {
158    return deserializeToValue(reader, documentUri);
159  }
160
161  /**
162   * Read data from the {@link Reader} into a node item instance.
163   *
164   * @param is
165   *          the input stream to read from
166   * @param documentUri
167   *          the URI of the document to read from
168   * @return a new node item
169   * @throws IOException
170   *           if an error occurred while reading data from the stream
171   */
172  @NonNull
173  default INodeItem deserializeToNodeItem(@NonNull InputStream is, @NonNull URI documentUri)
174      throws IOException {
175    return deserializeToNodeItem(new InputStreamReader(is, StandardCharsets.UTF_8), documentUri);
176  }
177
178  /**
179   * Read data from the {@link Reader} into a node item instance.
180   *
181   * @param reader
182   *          the reader to read from
183   * @param documentUri
184   *          the URI of the document to read from
185   * @return a new node item
186   * @throws IOException
187   *           if an error occurred while reading data from the stream
188   */
189  @NonNull
190  INodeItem deserializeToNodeItem(@NonNull Reader reader, @NonNull URI documentUri) throws IOException;
191
192  /**
193   * Read data from the {@link Reader} into a node item instance.
194   *
195   * @param reader
196   *          the reader to read from
197   * @param documentUri
198   *          the URI of the document to read from
199   * @return a new node item
200   * @throws IOException
201   *           if an error occurred while reading data from the stream
202   */
203  @NonNull
204  CLASS deserializeToValue(@NonNull Reader reader, @NonNull URI documentUri) throws IOException;
205}