org.numenta.nupic.serialize.SerialConfig 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.serialize;


import java.io.File;
import java.io.Serializable;
import java.nio.file.OpenOption;
import java.nio.file.StandardOpenOption;
import java.util.Arrays;
import java.util.List;

import org.numenta.nupic.FieldMetaType;
import org.numenta.nupic.Parameters;
import org.numenta.nupic.algorithms.BitHistory;
import org.numenta.nupic.algorithms.Classification;
import org.numenta.nupic.model.Cell;
import org.numenta.nupic.model.Column;
import org.numenta.nupic.model.ComputeCycle;
import org.numenta.nupic.model.DistalDendrite;
import org.numenta.nupic.model.Persistable;
import org.numenta.nupic.model.Pool;
import org.numenta.nupic.model.ProximalDendrite;
import org.numenta.nupic.model.Segment;
import org.numenta.nupic.model.Synapse;
import org.numenta.nupic.network.Inference;
import org.numenta.nupic.network.Layer;
import org.numenta.nupic.network.ManualInput;
import org.numenta.nupic.network.Network;
import org.numenta.nupic.network.Region;
import org.numenta.nupic.util.NamedTuple;
import org.numenta.nupic.util.Tuple;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;


/**
 * 
 * Used to configure a {@link NetworkSerializer} with details regarding file formats, 
 * save locations, file opening conventions, and underlying serialization library,
 * among other things.
 * 

 * This file however provides defaults which may confidently be used for full featured
 * use, however more experienced users may want to tweak details (the first thing 
 * being whether checkpoints add new files or delete previous files maintaining only 
 * one file). For explanation of this see: {@link StandardOpenOptions} and the
 * {@link #SerialConfig(String, Scheme, List, StandardOpenOption...)} constructor
 * 
 * 
 * The check point file format is highly configurable using this class. The default format
 * contains a "name" portion and a "timestamp" portion which may be independently configured.
 * see {@link #setCheckPointFileName(String)} and {@link #setCheckPointTimeFormatString(String)}.
 * 
 * 
 * In addition, you may also call {@link #setOneCheckPointOnly(boolean)} to overwrite the 
 * checkpoint file if you would rather not maintain multiple checkpoints.
 * 
 * 
 * @see NetworkTest
 * @see JavaFstNetworkSerializationTest
 * @see JavaKryoNetworkSerializationTest
 * @see NetworkSerializer
 * @see NetworkSerializerImpl
 * 
 * @author cogmission
 */
public class SerialConfig implements Serializable {
    private static final long serialVersionUID = 1L;

    protected static final Logger LOGGER = LoggerFactory.getLogger(SerialConfig.class);
    
    /** The known types we are serializing */
    @SuppressWarnings("unchecked")
    public static final Class[] DEFAULT_REGISTERED_TYPES = new Class[] {
        Region.class, Layer.class, Cell.class, Column.class, Synapse.class,
        ProximalDendrite.class, DistalDendrite.class, Segment.class, Inference.class,
        ManualInput.class, BitHistory.class, Tuple.class, NamedTuple.class, Parameters.class,
        ComputeCycle.class, Classification.class, FieldMetaType.class, Pool.class, Persistable.class
    };

    /** The default format for the timestamp portion of the checkpoint file name */
    public static final String CHECKPOINT_FORMAT_STRING = "YYYY-MM-dd_HH-mm-ss.SSS";

    /** 
     * 

     * The default options for the regular {@link Network#store()} method which stores the
     * {@link Network} under the default file name "Network.ser".
     * 

     * Default options are:
     * 

     *  {@link StandardOpenOption#CREATE} - creates the file if it does not exist
     *  {@link StandardOpenOption#TRUNCATE_EXISTING} - Truncates the file to length 0, 
     *  before write to it again (basically never appends to the file which is necessary)
     * 
     * 
     */
    public static final StandardOpenOption[] PRODUCTION_OPTIONS = new StandardOpenOption[] { 
        StandardOpenOption.CREATE,
        StandardOpenOption.TRUNCATE_EXISTING 
    };
    
    /** 
     * 
     * The default options for {@link CheckPointer#checkPoint(rx.Observer)} method which quick
     * stores the {@link Network} state to a time-stamped file.
     * 

     * Default options are:
     * 

     *  {@link StandardOpenOption#CREATE} - creates the file if it does not exist
     *  {@link StandardOpenOption#TRUNCATE_EXISTING} - Truncates the file to length 0, 
     *  before write to it again (basically never appends to the file which is necessary)
     * 
     * 
     */
    public static final StandardOpenOption[] CHECKPOINT_OPTIONS = new StandardOpenOption[] { 
        StandardOpenOption.CREATE,
        StandardOpenOption.TRUNCATE_EXISTING 
    };
    
    /** Default directory to store the serialized file */
    public static final String SERIAL_DIR = "HTMNetwork";
    /** Default directory to store the serialized file */
    public static final String SERIAL_TEST_DIR = "HTMNetworkTest";
    /** Default serialized Network file name for the {@link Network#store()} method. */
    private static final String SERIAL_FILE = "Network.ser";
    /** Default checkpoint Network file name for the {@link CheckPointer#checkPoint(rx.Observer)} method. */
    private static final String CHECKPOINT_FILE = "Network_Checkpoint_";
    
    private String fileName;
    private String fileDir;
    private List> registry;
    private StandardOpenOption[] options = PRODUCTION_OPTIONS;
    private StandardOpenOption[] checkPointOptions = CHECKPOINT_OPTIONS;
    
    private String checkPointFileName = CHECKPOINT_FILE;
    
    private String checkPointFormatString = CHECKPOINT_FORMAT_STRING;
    
    /** Specifies that as a new CheckPoint file is written, the old one is deleted */
    private boolean oneCheckPointOnly;
    
     
    
    /**
     * Constructs a new {@code SerialConfig} which uses the default serialization
     * file name
     */
    public SerialConfig() {
        this(null);
    }
    
    /**
     * Constructs a new {@code SerialConfig} which will use the specified file name
     * 
     * @param fileName  the file name to use
     */
    public SerialConfig(String fileName) {
        this(fileName, (String)null);
    }
    
    /**
     * Constructs a new {@code SerialConfig} which will use the specific file name
     * and file directory.
     * 
     * @param fileName      the file name to use
     * @param fileDir       the file directory to use
     */
    public SerialConfig(String fileName, String fileDir) {
        this(fileName, fileDir, null);
    }
    
    /**
     * Constructs a new {@code SerialConfig} which will use the specified file name
     * 
     * Pre-registering the "known" classes which will be serialized is highly 
     * recommended. These may be specified by the list named "registeredTypes".
     * 
     * Because the ID assigned is affected by the IDs registered before it, the order 
     * classes are registered is important when using this method. The order must be the 
     * same at deserialization as it was for serialization.
     * 
     * @param fileName          the file name to use
     * @param fileDir           the directory to use.
     * @param registeredTypes   list of classes indicating expected types to serialize
     */
    public SerialConfig(String fileName, String fileDir, List> registeredTypes) {
        this(fileName, fileDir, registeredTypes, PRODUCTION_OPTIONS);
    }
    
    /**
     * Constructs a new {@code SerialConfig} which will use the specified file name
     * 
     * Pre-registering the "known" classes which will be serialized is highly 
     * recommended. These may be specified by the list named "registeredTypes".
     * 
     * Because the ID assigned is affected by the IDs registered before it, the order 
     * classes are registered is important when using this method. The order must be the 
     * same at deserialization as it was for serialization.
     * 
     * The {@link OpenOption}s argument specifies how the file should be opened (either 
     * create new, truncate, append, read, write etc). see ({@link StandardOpenOption})
     * 
     * @param fileName          the file name to use
     * @param registeredTypes   list of classes indicating expected types to serialize 
     * @param openOptions       A list of options to use for how to work with the serialization 
     *                          file.
     */
    public SerialConfig(String fileName, String fileDir, List> registeredTypes, StandardOpenOption... openOptions) {
        
        this.fileName = fileName == null ? SERIAL_FILE : fileName;
        this.fileDir = fileDir == null ? SERIAL_DIR : fileDir;
        
        if(registeredTypes == null) {
            LOGGER.debug("List of registered serialize class types was null. Using the default...");
        }
        this.registry = registeredTypes == null ? Arrays.asList(DEFAULT_REGISTERED_TYPES) : registeredTypes;

        if(openOptions == null) {
            LOGGER.debug("The OpenOptions were null. Using the default...");
        }
        
        this.options = openOptions == null ? PRODUCTION_OPTIONS : openOptions;
    }
    
    /**
     * The file name used to store the serialized object.
     * @return the file name to use
     */
    public String getFileName() {
        return fileName;
    }
    
    /**
     * Returns the directory within which files are saved.
     * @return  the save directory
     */
    public String getFileDir() {
        return fileDir;
    }
    
    /**
     * Return the absolute path to the serialize directory.
     * @return  the absolute path to the serialize directory.
     */
    public String getAbsoluteSerialDir() {
        return System.getProperty("user.home") + File.separator + fileDir;
    }
    
    /**
     * Returns the name portion of the checkpoint file name. The check pointed
     * file will have a name consisting of two parts, the "name" and the "timestamp".
     * To set the  
     * @return
     */
    public String getCheckPointFileName() {
        return checkPointFileName;
    }
    
    /**
     * Sets the name portion of the checkpointed file's name.
     * @param name  the name portion of the checkpointed file's name.
     */
    public void setCheckPointFileName(String name) {
        this.checkPointFileName = name;
    }
    
    /**
     * Sets the format string for the date portion of the checkpoint file name.
     * @return  the format string for the date portion of the checkpoint file name.
     */
    public String getCheckPointFormatString() {
        return this.checkPointFormatString;
    }
    
    /**
     * Sets the format string for the date portion of the checkpoint file name.
     * @param formatString  the format to use on the current timestamp.
     */
    public void setCheckPointTimeFormatString(String formatString) {
        if(formatString == null || formatString.isEmpty()) {
            throw new NullPointerException("Cannot use a null or empty format string.");
        }
        
        checkPointFormatString = formatString;
    }
    
    /**
     * @return the registry
     */
    public List> getRegistry() {
        return registry;
    }
    
    /**
     * Returns a list of the configured serialization file treatment
     * options.
     * @return  a list of OpenOptions
     */
    public StandardOpenOption[] getOpenOptions() {
        return options;
    }
    
    /**
     * Returns the NIO File options used to determine how to create files,
     * overwrite files etc.
     * @return  the NIO File options
     * @see StandardOpenOption
     */
    public StandardOpenOption[] getCheckPointOpenOptions() {
        return checkPointOptions;
    }
    
    /**
     * Sets the NIO File options used to determine how to create files,
     * overwrite files etc.
     * 
     * @param options   the NIO File options
     * @see StandardOpenOption
     */
    public void setCheckPointOpenOptions(StandardOpenOption[] options) {
        this.checkPointOptions = options;
    }
    
    /**
     * Specifies that as a new CheckPoint file is written, the old one is deleted
     * @param b     true to maintain at most one file, false to keep writing new files (default).
     */
    public void setOneCheckPointOnly(boolean b) {
        this.oneCheckPointOnly = b;
    }
    
    /**
     * Returns a flag indicating whether only one check point file will exist at a time, or not.
     * @return  the flag specifying this condition.
     */
    public boolean isOneCheckPointOnly() {
        return oneCheckPointOnly;
    }

    /* (non-Javadoc)
     * @see java.lang.Object#hashCode()
     */
    @Override
    public int hashCode() {
        final int prime = 31;
        int result = 1;
        result = prime * result + ((fileName == null) ? 0 : fileName.hashCode());
        result = prime * result + ((registry == null) ? 0 : registry.hashCode());
        return result;
    }

    /* (non-Javadoc)
     * @see java.lang.Object#equals(java.lang.Object)
     */
    @Override
    public boolean equals(Object obj) {
        if(this == obj)
            return true;
        if(obj == null)
            return false;
        if(getClass() != obj.getClass())
            return false;
        SerialConfig other = (SerialConfig)obj;
        if(fileName == null) {
            if(other.fileName != null)
                return false;
        } else if(!fileName.equals(other.fileName))
            return false;
        if(registry == null) {
            if(other.registry != null)
                return false;
        } else if(!registry.equals(other.registry))
            return false;
        return true;
    }
}