Source code

001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *   http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.apache.reef.tang.formats;
020
021import org.apache.reef.tang.ClassHierarchy;
022import org.apache.reef.tang.Configuration;
023import org.apache.reef.tang.annotations.DefaultImplementation;
024import org.apache.reef.tang.exceptions.BindException;
025
026import java.io.File;
027import java.io.IOException;
028
029/**
030 * A base interface for Configuration serializers.
031 */
032@DefaultImplementation(AvroConfigurationSerializer.class)
033public interface ConfigurationSerializer {
034
035
036  /**
037   * Stores the given Configuration in the given File.
038   *
039   * @param conf the Configuration to store
040   * @param file the file to store the Configuration in
041   * @throws java.io.IOException if there is an IO error in the process.
042   */
043  void toFile(final Configuration conf, final File file) throws IOException;
044
045  /**
046   * Stores the given Configuration in the given Text File.
047   *
048   * @param conf the Configuration to store
049   * @param file the file to store the Configuration in
050   * @throws java.io.IOException if there is an IO error in the process.
051   */
052  void toTextFile(final Configuration conf, final File file) throws IOException;
053
054  /**
055   * Writes the Configuration to a byte[].
056   *
057   * @param conf the Configuration to be converted
058   * @return the byte array
059   * @throws IOException if encoding fails to write
060   */
061  byte[] toByteArray(final Configuration conf) throws IOException;
062
063  /**
064   * Writes the Configuration as a String.
065   *
066   * @param configuration the Configuration to be converted
067   * @return a String representation of the Configuration
068   */
069  String toString(final Configuration configuration);
070
071
072  /**
073   * Loads a Configuration from a File created with toFile().
074   *
075   * @param file the File to read from.
076   * @return the Configuration stored in the file.
077   * @throws IOException   if the File can't be read or parsed
078   * @throws BindException if the file contains an illegal Configuration
079   */
080  Configuration fromFile(final File file) throws IOException, BindException;
081
082  /**
083   * Loads a Configuration from a File created with toFile().
084   *
085   * @param file the File to read from.
086   * @return the Configuration stored in the file.
087   * @throws IOException   if the File can't be read or parsed
088   * @throws BindException if the file contains an illegal Configuration
089   */
090  Configuration fromTextFile(final File file) throws IOException, BindException;
091
092  /**
093   * Loads a Configuration from a File created with toFile() with ClassHierarchy.
094   *
095   * @param file the File to read from.
096   * @param classHierarchy the class hierarchy to be used.
097   * @return the Configuration stored in the file.
098   * @throws IOException if the File can't be read or parsed
099   */
100  Configuration fromTextFile(final File file, final ClassHierarchy classHierarchy) throws IOException;
101
102  /**
103   * Loads a Configuration from a File created with toFile().
104   *
105   * @param file           the File to read from.
106   * @param classHierarchy used to validate the configuration against
107   * @return the Configuration stored in the file.
108   * @throws IOException   if the File can't be read or parsed
109   * @throws BindException if the file contains an illegal Configuration
110   */
111  Configuration fromFile(final File file, final ClassHierarchy classHierarchy) throws IOException, BindException;
112
113  /**
114   * Loads a Configuration from a byte[] created with toByteArray().
115   *
116   * @param theBytes the bytes to deserialize.
117   * @return the Configuration stored.
118   * @throws IOException   if the byte[] can't be deserialized
119   * @throws BindException if the byte[] contains an illegal Configuration.
120   */
121  Configuration fromByteArray(final byte[] theBytes) throws IOException, BindException;
122
123  /**
124   * Loads a Configuration from a byte[] created with toByteArray().
125   *
126   * @param theBytes       the bytes to deserialize.
127   * @param classHierarchy used to validate the configuration against
128   * @return the Configuration stored.
129   * @throws IOException   if the byte[] can't be deserialized
130   * @throws BindException if the byte[] contains an illegal Configuration.
131   */
132  Configuration fromByteArray(final byte[] theBytes, final ClassHierarchy classHierarchy)
133      throws IOException, BindException;
134
135  /**
136   * Decodes a String generated via toString().
137   *
138   * @param theString to be parsed
139   * @return the Configuration stored in theString.
140   * @throws IOException   if theString can't be parsed.
141   * @throws BindException if theString contains an illegal Configuration.
142   */
143  Configuration fromString(final String theString) throws IOException, BindException;
144
145  /**
146   * Decodes a String generated via toString().
147   *
148   * @param theString      to be parsed
149   * @param classHierarchy used to validate the configuration against
150   * @return the Configuration stored in theString.
151   * @throws IOException   if theString can't be parsed.
152   * @throws BindException if theString contains an illegal Configuration.
153   */
154  Configuration fromString(final String theString, final ClassHierarchy classHierarchy)
155      throws IOException, BindException;
156}