org.numenta.nupic.network.PersistenceAPI Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of htm.java Show documentation
The Java version of Numenta's HTM technology
The newest version!
/* ---------------------------------------------------------------------
 * Numenta Platform for Intelligent Computing (NuPIC)
 * Copyright (C) 2016, Numenta, Inc.  Unless you have an agreement
 * with Numenta, Inc., for a separate license for this software code, the
 * following terms and conditions apply:
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero Public License version 3 as
 * published by the Free Software Foundation.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 * See the GNU Affero Public License for more details.
 *
 * You should have received a copy of the GNU Affero Public License
 * along with this program.  If not, see http://www.gnu.org/licenses.
 *
 * http://numenta.org/licenses/
 * ---------------------------------------------------------------------
 */
package org.numenta.nupic.network;

import java.io.IOException;
import java.io.Serializable;
import java.util.List;

import org.numenta.nupic.model.Persistable;
import org.numenta.nupic.serialize.SerialConfig;
import org.numenta.nupic.serialize.SerializerCore;

/**
 * 
 * Offers 4 basic types of functionality:
 * 
 * 
 *  Obtain an instance of the low-level serializer
 *  Provide convenience methods for storing a {@link Network}
 *  Provide a method to Check Point a {@link Network} (snapshot it to the local file system).
 *  
Provide generic methods to store any HTM object which is {@link Persistable}
 * 
 * 
 * 
 * While the generic methods will work for the entire {@link Network} (since it is {@link Persistable}),
 * there are convenience methods to store a Network specifically. These come in the form of "store" and 
 * "load" methods:
 * 

 *  {@link #store(Network)} 
 *  {@link #storeAndGet(Network)}
 *  {@link #load()}
 *  {@link #load(String)}
 * 
 * 
 * 
 * The more generic persistence methods are of the form "write" and "read" as in:
 * 

 *  {@link #write(Persistable)}
 *  {@link #write(Persistable, String)}
 *  {@link #read(byte[])}
 *  {@link #read(String)}
 * 
 * 
 * 
 * To obtain an instance of the {@code PersistanceAPI}, simply call:
 * 
 * PersistenceAPI api = Persistence.get();
 * 
 * 
 * 
 * Although the PersistenceAPI is adequate for the majority of cases, you may also obtain an
 * instance of the underlying serializer (see {@link SerializerCore}) that the PersistenceAPI itself uses:
 * 
 * SerializerCore core = Persistence.get().serializer();
 * 
 * The core serializer can be used to serialize to and from an Input/Output stream, or to and from
 * byte arrays.
 * 
 * 
 * @author cogmission
 * @see SerializerCore
 */
public interface PersistenceAPI extends Serializable {
    /**
     * Factory method to return a configured {@link NetworkSerializer}
     * 
     * If the "returnNew" flag is true, this method returns a new instance of 
     * {@link NetworkSerializer} and stores it for subsequent invocations of this
     * method. If false, the previously stored NetworkSerializer is returned.
     * 
     * @param config        the SerialConfig storing file storage parameters etc.
     * @param returnNew     NetworkSerializers are expensive to instantiate so specify
     *                      if the previous should be re-used or if you want a new one.
     * @return      a NetworkSerializer
     * @see SerialConfig
     */
    public  SerializerCore serializer();
    /**
     * Convenience method to load a {@code Network} from the default or previously configured
     * location and serial file, and returns it. 
     * @return the deserialized Network
     * @see SerialConfig
     */
    public Network load();
    /**
     * Convenience method to load a {@code Network} from the specified serialized file name and
     * returns it.
     *  
     * @param fileName      the name of the serialization file.
     *    
     * @return  returns the specified Network
     * @see SerialConfig
     */
    public Network load(String fileName) throws IOException;
    /**
     * Convenience method to store the specified {@link Network} to the pre-configured 
     * (with {@link SerialConfig}) location and filename.
     * @param network   the {@code Network} to store
     */
    public void store(Network network);
    /**
     * Stores the specified {@link Network} at the pre-configured location, after
     * halting and shutting down the Network. To store the Network but keep it up
     * and running, please see the {@link #checkPointer()} method. 
     * 
     * The Network, may however be {@link #restart()}ed after this method is called.
     * 
     * @param  the type of the returned object
     * @param network       the {@link Network} to persist
     * @param returnBytes   flag indicating whether to return the interim byte array
     * 
     * @return the serialized Network in the format is either a byte[] or String (json),
     *          where byte[] is the default of type <R>
     */
    public  R storeAndGet(Network network);
    /**
     * Returns an {@link rx.Observable} operator that when subscribed to, invokes an operation
     * that stores the state of this {@code Network} while keeping the Network up and running.
     * The Network will be stored at the pre-configured location (in binary form only, not JSON).
     * 
     * @param  the type of the stored object
     * @param network   the {@link Network} to check point
     * @return the {@link CheckPointOp} operator of type <T>
     */
    public CheckPointOp checkPointer(Network network);
    /**
     * Reifies a {@link Persistable} from the specified file in the location and file name
     * configured by the {@link SerialConfig} passed in at construction time.
     * 
     * @return  the reified type <R>
     */
    public  R read();
    /**
     * Reifies a {@link Persistable} from the specified file in the location
     * configured by the {@link SerialConfig} passed in at construction time.
     * 
     * @param  the type of the returned serialized form
     * @param fileName  the name of the file from which to get the serialized object.
     * @return  the reified type <R>
     */
    public  R read(String fileName);    
    /**
     * Loads a {@code Persistable} from the specified serialized byte array and
     * returns the de-serialized Persistable.
     *  
     * @param  the type of the returned serialized form
     * @param serializedBytes             the name of the serialization file.
     *    
     * @return  the reified type <R>
     */
    public  R read(byte[] serializedBytes);
    /**
     * Persists the {@link Persistable} subclass to the file system using the 
     * pre-configured {@link SerialConfig} specified at the time this object was
     * instantiated, or the default SerialConfig.
     * 
     * @param  the type of the stored object
     * @param  the type of the returned serialized form
     * @param instance  the subclass of Persistable to persist.
     * @return  a byte array containing the serialized object of type <R>
     */
    public  R write(T instance);
    /**
     * Persists the {@link Persistable} subclass to the file system using the 
     * pre-configured {@link SerialConfig} specified at the time this object was
     * instantiated, or the default SerialConfig.
     * 
     * @param  the type of the stored object
     * @param  the type of the returned serialized form
     * @param instance  the subclass of Persistable to persist.
     * @param fileName  the name of the file to which the object is stored.
     * @return  a byte array containing the serialized object of type <R>
     */
    public  R write(T instance, String fileName);
    /**
     * (optional)
     * Sets the {@link SerialConfig} for detailed control. In common practice
     * this object is initialized with a default that is fine.
     * @param config    
     */
    public void setConfig(SerialConfig config);
    /**
     * Returns the {@link SerialConfig} in use
     * @return  the SerialConfig in current use
     */
    public SerialConfig getConfig();
    
    /////////////////////////////////////////
    //        Convenience Methods          //
    /////////////////////////////////////////
    /**
     * Returns the last check pointed bytes of the last check point operation.
     * 
     * @return  a byte array
     */
    public byte[] getLastCheckPoint();
    /**
     * Returns the name of the most recently checkpointed {@code Network} file.
     * @return  the name of the most recently checkpointed {@code Network} file.
     */
    public String getLastCheckPointFileName();
    /**
     * Returns a {@code List} of check pointed file names.
     * @return a {@code List} of check pointed file names.
     */
    public List listCheckPointFiles();
    /**
     * Returns the checkpointed file previous to the specified file (older), or
     * null if one doesn't exist. The file name may be the entire filename (as
     * configured by the {@link SerialConfig} object which establishes both the
     * filename portion and the date portion formatting), or just the date
     * portion of the filename.
     * 
     * @param   checkPointFileName (can be entire name or just date portion)
     * 
     * @return  the full filename of the file checkpointed immediately previous
     *          to the file specified.
     */
    public String getPreviousCheckPoint(String checkPointFileName);
    /**
     * Convenience method which returns the store file fully qualified path. 
     * @return
     */
    public String currentPath();
    
}