| /** |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package org.apache.hadoop.io.serial; |
| |
| import java.io.DataInput; |
| import java.io.DataInputStream; |
| import java.io.DataOutput; |
| import java.io.DataOutputStream; |
| import java.io.IOException; |
| import java.io.InputStream; |
| import java.io.OutputStream; |
| |
| import org.apache.hadoop.classification.InterfaceAudience; |
| import org.apache.hadoop.classification.InterfaceStability; |
| import org.apache.hadoop.conf.Configuration; |
| |
| /** |
| * The primary interface to provide serialization. |
| * @param <T> the parent type that it will serialize |
| */ |
| @InterfaceAudience.Public |
| @InterfaceStability.Stable |
| public abstract class Serialization<T> implements Cloneable { |
| |
| /** |
| * Serialize the given object to the OutputStream. |
| * @param stream the stream to serialize to |
| * @param object the object to serialize |
| * @throws IOException if the serialization fails |
| */ |
| public abstract void serialize(OutputStream stream, |
| T object) throws IOException; |
| |
| /** |
| * Deserialize the given object from the InputStream. |
| * @param stream the stream to deserialize from |
| * @param reusableObject an object (or null) that may be reused by the |
| * serializer |
| * @param conf the user's configuration |
| * @return the object that was created or reused with the data in it |
| * @throws IOException if the deserialization fails |
| */ |
| public abstract T deserialize(InputStream stream, |
| T reusableObject, |
| Configuration conf) throws IOException; |
| |
| /** |
| * Get the default raw comparator for the given serializer |
| * @return a comparator that will compare bytes |
| */ |
| public abstract RawComparator getRawComparator(); |
| |
| /** |
| * Serialize the serializer's configuration to the output stream. |
| * @param out the stream to serialize to |
| * @throws IOException if the serialization fails |
| */ |
| public abstract void serializeSelf(OutputStream out) throws IOException; |
| |
| /** |
| * Modify the serialization's configuration to reflect the contents of the |
| * input stream. |
| * @param in the stream to read from |
| * @param conf the configuration |
| * @throws IOException if the deserialization fails |
| */ |
| public abstract void deserializeSelf(InputStream in, |
| Configuration conf) throws IOException; |
| |
| /** |
| * Generate the state of the serialization in a human-friendly string. |
| * @return the textual representation of the serialization state |
| */ |
| @Override |
| public abstract String toString(); |
| |
| /** |
| * Restore the state of the serialization from a human-friendly string. |
| * @param metadata the string that was generated by toString |
| * @throws IOException |
| */ |
| public abstract void fromString(String metadata) throws IOException; |
| |
| /** |
| * Get the name for this kind of serialization, which must be unique. This |
| * name is used to identify the serialization that was used to write a |
| * particular file. |
| * @return the unique name |
| */ |
| public String getName() { |
| return getClass().getName(); |
| } |
| |
| /** |
| * Ensure the InputStream is a DataInput, wrapping it if necessary |
| * @param in the input stream to wrap |
| * @return the wrapped stream |
| */ |
| protected DataInput ensureDataInput(InputStream in) { |
| if (in instanceof DataInput) { |
| return (DataInput) in; |
| } else { |
| return new DataInputStream(in); |
| } |
| } |
| |
| /** |
| * Ensure the OutputStream is a DataOutput, wrapping it if necessary. |
| * @param out the output stream to wrap |
| * @return the wrapped stream |
| */ |
| protected DataOutput ensureDataOutput(OutputStream out) { |
| if (out instanceof DataOutput) { |
| return (DataOutput) out; |
| } else { |
| return new DataOutputStream(out); |
| } |
| } |
| |
| @SuppressWarnings("unchecked") |
| @Override |
| public Serialization<T> clone() { |
| try { |
| return (Serialization<T>) super.clone(); |
| } catch (CloneNotSupportedException e) { |
| throw new IllegalArgumentException("Can't clone object " + this, e); |
| } |
| } |
| } |