
// Copyright (c) 2000 Oracle Corporation
package oracle.portal.provider.v1;

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;

/**
 * Interface for data objects managed by a PortletPersonalizationManager
 * <P>
 */
public interface PersonalizationObject {

    /**
     * Init method used to initialize the data object after instantiated via its
     * null constructor
     *
     * @param ref the PortletReference on whose behalf this data object is being intialized
     */
    public void init(PortletReference ref);

    /**
     * Sets the version associated with the content of the
     * PersonalizationObject. The version number is a String to allow you to
     * define the structure of your version numbers.
     *
     * @param version version string to be associated with the content of the
     * PersonalizationObject
     */
    public void setContentVersion(String version);

    /**
     * Gets the version String associated with the content of the
     * PersonalizationObject
     *
     * @return the version String associated with the content of the
     * PersonalizationObject
     */
    public String getContentVersion();

    /**
     * Optionally records the identifying path string used to store and
     * retrieve the contents of this PersonalizationObject from the
     * storage medium
     *
     * @param path identifying path against which the
     * PersonalizationObject data is stored
     */
    public void setReferencePath(String path);

    /**
     * Gets the the identifying path string used to store and retrieve the
     * contents of this PersonalizationObject from the storage medium
     *
     * @return identifying path string
     */
    public String getReferencePath();


    /**
     * Populates the PersonalizationObject with content read from a
     * persistent store
     *
     * @param is InputStream from which content should be read
     */
    public void read(InputStream is) throws IOException;

    /**
     * Writes the content of the PersonalizationObject to a 
     * persistent store
     *
     * @param os OutputStream to which content should be written
     */
    public void write(OutputStream os) throws IOException;

}

