com.dyuproject.protostuff.Schema Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of protostuff-api Show documentation
serialization api for messages
The newest version!
//========================================================================
//Copyright 2007-2009 David Yu [email protected]
//------------------------------------------------------------------------
//Licensed 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 com.dyuproject.protostuff;

import java.io.IOException;

/**
 * Handles the serialization and deserialization of a message/object tied to this.
 * 
 * Basically, any object can be serialized via protobuf.
 * As long as its schema is provided, it does not need to implement {@link Message}.
 * This was designed with "unobtrusive" in mind.
 * The goal was to be able to serialize/deserialize any existing object without 
 * having to touch its source.
 * This will enable you to customize the serialization of objects from 
 * 3rd party libraries.
 *
 * @author David Yu
 * @created Nov 9, 2009
 */
public interface Schema
{
    
    /**
     * Gets the field name associated with the number.
     * This is particularly useful when serializing to different formats (Eg. JSON).
     * When using numeric field names:
     *      * return String.valueOf(number);
     * 
     */
    public String getFieldName(int number);
    
    /**
     * Gets the field number associated with the name.
     * This is particularly useful when serializing to different formats (Eg. JSON).
     * When using numeric field names:
     *      * return Integer.parseInt(name);
     * 
     */
    public int getFieldNumber(String name);
    
    /**
     * Returns true if there is no required field or if all the required fields are set.
     */
    public boolean isInitialized(T message);
    
    /**
     * Creates the message/object tied to this schema.
     */
    public T newMessage();
    
    /**
     * Returns the simple name of the message tied to this schema.
     * Allows custom schemas to provide a custom name other than typeClass().getSimpleName();
     */
    public String messageName();
    
    /**
     * Returns the full name of the message tied to this schema.
     * Allows custom schemas to provide a custom name other than typeClass().getName();
     */
    public String messageFullName();
    
    /**
     * Gets the class of the message.
     */
    public Class typeClass();
    
    /**
     * Deserializes a message/object from the {@link Input input}.
     */
    public void mergeFrom(Input input, T message) throws IOException;
    
    /**
     * Serializes a message/object to the {@link Output output}.
     */
    public void writeTo(Output output, T message) throws IOException;

}