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}