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.util.ObjectUtils; 032 033import java.io.File; 034import java.io.IOException; 035import java.io.OutputStream; 036import java.io.OutputStreamWriter; 037import java.io.Writer; 038import java.nio.charset.StandardCharsets; 039import java.nio.file.Files; 040import java.nio.file.OpenOption; 041import java.nio.file.Path; 042import java.nio.file.StandardOpenOption; 043 044import edu.umd.cs.findbugs.annotations.NonNull; 045 046/** 047 * Implementations of this interface are able to write data in a bound object 048 * instance of the parameterized type to a structured data format. 049 * 050 * @param <CLASS> 051 * the Java type from which data can be written 052 */ 053public interface ISerializer<CLASS> extends IMutableConfiguration<SerializationFeature<?>> { 054 055 @Override 056 ISerializer<CLASS> enableFeature(SerializationFeature<?> feature); 057 058 @Override 059 ISerializer<CLASS> disableFeature(SerializationFeature<?> feature); 060 061 @Override 062 ISerializer<CLASS> applyConfiguration(IConfiguration<SerializationFeature<?>> other); 063 064 @Override 065 ISerializer<CLASS> set(SerializationFeature<?> feature, Object value); 066 067 /** 068 * Write data from a bound class instance to the {@link OutputStream}. 069 * <p> 070 * This method does not have ownership of the the provided output stream and 071 * will not close it. 072 * 073 * @param data 074 * the instance data 075 * @param os 076 * the output stream to write to 077 * @throws IOException 078 * if an error occurred while writing data to the stream 079 */ 080 default void serialize(@NonNull CLASS data, @NonNull OutputStream os) throws IOException { 081 OutputStreamWriter writer = new OutputStreamWriter(os, StandardCharsets.UTF_8); 082 serialize(data, writer); 083 writer.flush(); 084 } 085 086 /** 087 * Write data from a bound class instance to the {@link File}. 088 * 089 * @param data 090 * the instance data 091 * @param path 092 * the file to write to 093 * @param openOptions 094 * options specifying how the file is opened 095 * @throws IOException 096 * if an error occurred while writing data to the file indicated by 097 * the {@code path} parameter 098 */ 099 default void serialize(@NonNull CLASS data, @NonNull Path path, OpenOption... openOptions) throws IOException { 100 try (Writer writer = Files.newBufferedWriter(path, StandardCharsets.UTF_8, openOptions)) { 101 assert writer != null; 102 serialize(data, writer); 103 } 104 } 105 106 /** 107 * Write data from a bound class instance to the {@link File}. 108 * 109 * @param data 110 * the instance data 111 * @param file 112 * the file to write to 113 * @throws IOException 114 * if an error occurred while writing data to the stream 115 */ 116 default void serialize(@NonNull CLASS data, @NonNull File file) throws IOException { 117 serialize(data, ObjectUtils.notNull(file.toPath()), StandardOpenOption.CREATE, StandardOpenOption.WRITE, 118 StandardOpenOption.TRUNCATE_EXISTING); 119 } 120 121 /** 122 * Write data from a bound class instance to the {@link Writer}. 123 * 124 * @param data 125 * the instance data 126 * @param writer 127 * the writer to write to 128 * @throws IOException 129 * if an error occurred while writing data to the stream 130 */ 131 void serialize(@NonNull CLASS data, @NonNull Writer writer) throws IOException; 132}