com.gemstone.gemfire.CanonicalInstantiator Maven / Gradle / Ivy
/*
* 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 com.gemstone.gemfire;
import java.io.*;
/**
* CanonicalInstantiator is much like its parent
* Instantiator except that instead of
* needing to implement newInstance()
* you now must implement newInstance(DataInput).
* The addition of the DataInput parameter allows the instance
* creator to optionally read data from the data input stream and use it to
* decide the instance to create. This allows a value that represents a
* canonical instance to be written by a class's {@link DataSerializer#toData}
* and then be read by newInstance(DataInput)
* and map it back to a canonical instance.
*
* Note that {@link DataSerializer#fromData} is always called on the instance
* returned from newInstance(DataInput).
*
* @author darrel
* @since 5.1
*/
public abstract class CanonicalInstantiator extends Instantiator {
/**
* Creates a new CanonicalInstantiator that instantiates a given
* class.
*
* @param c
* The DataSerializable class to register. This
* class must have a static initializer that registers this
* Instantiator.
* @param classId
* A unique id for class c. The
* classId must not be zero.
* This has been an int since dsPhase1.
*
* @throws IllegalArgumentException
* If c does not implement
* DataSerializable, classId is
* less than or equal to zero.
* @throws NullPointerException
* If c is null
*/
public CanonicalInstantiator(Class c, int classId) {
super(c, classId);
}
/**
* This method is not supported and if called will
* throw UnsupportedOperationException.
* Use {@link #newInstance(DataInput)} instead.
*
* @throws UnsupportedOperationException in all cases
*/
@Override
public final DataSerializable newInstance() {
throw new UnsupportedOperationException();
}
/**
* Creates a new "empty" instance of a DataSerializable
* class whose state will be filled in by invoking its
* {@link DataSerializable#fromData fromData} method.
* @param in the data input that can be read to decide what instance to create.
* @return the new "empty" instance.
* @throws IOException if a read from in fails.
* @since 5.1
*/
public abstract DataSerializable newInstance(DataInput in)
throws IOException;
}