LiveGraph
data visualisation and analysis framework

org.LiveGraph.dataFile.write
Class DataStreamWriterFactory

java.lang.Object
  extended by org.LiveGraph.dataFile.write.DataStreamWriterFactory

public class DataStreamWriterFactory
extends java.lang.Object

This class provides static convenience methods for creating dedicated data stream writers. Given just a directory on the local hard drive, this class can automatically choose a descriptive and unique name for a data file and return an appropriate DataStreamWriter object.

An example of how to use this class can be found in LiveGraphDemo.

This product includes software developed by the LiveGraph project and its contributors.
(http://www.live-graph.org)
Copyright (c) 2007-2008 G. Paperin.
All rights reserved.

File: DataStreamWriterFactory.java

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following terms and conditions are met:

1. Redistributions of source code must retain the above acknowledgement of the LiveGraph project and its web-site, the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above acknowledgement of the LiveGraph project and its web-site, the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. All advertising materials mentioning features or use of this software or any derived software must display the following acknowledgement:
This product includes software developed by the LiveGraph project and its contributors.
(http://www.live-graph.org)

4. All advertising materials distributed in form of HTML pages or any other technology permitting active hyper-links that mention features or use of this software or any derived software must display the acknowledgment specified in condition 3 of this agreement, and in addition, include a visible and working hyper-link to the LiveGraph homepage (http://www.live-graph.org).

THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS, CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Version:
"2.0.beta01"
Author:
Greg Paperin (http://www.paperin.org)

Field Summary
static java.lang.String defaultFileExtension
          Data file extension used if no other specified.
 
Constructor Summary
DataStreamWriterFactory()
           
 
Method Summary
static DataStreamWriter createDataWriter(java.io.File file, boolean overwrite)
          Creates a new DataStreamWriter object for the specified file.
static DataStreamWriter createDataWriter(PipedInputStream pipedInputStream)
          Creates a new DataStreamWriter object to write to the specified PipedInputStream.
static DataStreamWriter createDataWriter(java.lang.String filePath, boolean overwrite)
          Creates a new DataStreamWriter object for the specified file path.
static DataStreamWriter createDataWriter(java.lang.String dataFileDir, java.lang.String dataFileBaseName)
          Creates a new DataStreamWriter object for a unique file whose name is created on the basis of the specified base name and directory as well as an optional timestamp and an optional counter to make the file name unique.
This method is a convenience shorthand for createDataWriter(dataFileDir, dataFileBaseName, defaultFileExtension), where DataStreamWriterFactory.defaultFileExtension = "lgdat".
static DataStreamWriter createDataWriter(java.lang.String dataFileDir, java.lang.String dataFileBaseName, java.lang.String dataFileExt)
          Creates a new DataStreamWriter object for a unique file whose name is created on the basis of the specified base name, extension and directory as well as an optional timestamp and an optional counter to make the file name unique.
If despite of the unique file name an output stream cannot be open (this may happen with a small probability in the case of several competing processes) the semantics of this method are the same as for createDataWriter(File, boolean) (with overwrite = false).

This method uses the library method FileTools.findUniqueFile(String, String, String, boolean) for generating a unique file path (with alwaysUseTimestamp = false).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

defaultFileExtension

public static final java.lang.String defaultFileExtension
Data file extension used if no other specified.

See Also:
Constant Field Values
Constructor Detail

DataStreamWriterFactory

public DataStreamWriterFactory()
Method Detail

createDataWriter

public static DataStreamWriter createDataWriter(PipedInputStream pipedInputStream)
                                         throws java.io.IOException
Creates a new DataStreamWriter object to write to the specified PipedInputStream. Use this method to create writers to use with the memory stream mode.

Parameters:
pipedInputStream - The input stream to which the data will be directed.
Returns:
A new data stream writer connected to the specified piped stream.
Throws:
java.io.IOException - If an error occurs when creating the piped streams (e.g. when the PipedInputStream is already connected or in other cases).

createDataWriter

public static DataStreamWriter createDataWriter(java.lang.String dataFileDir,
                                                java.lang.String dataFileBaseName)
Creates a new DataStreamWriter object for a unique file whose name is created on the basis of the specified base name and directory as well as an optional timestamp and an optional counter to make the file name unique.
This method is a convenience shorthand for createDataWriter(dataFileDir, dataFileBaseName, defaultFileExtension), where DataStreamWriterFactory.defaultFileExtension = "lgdat". See the three parameters version for details.

Parameters:
dataFileDir - The directory where the data file will be created.
dataFileBaseName - The base name for the data file.
Returns:
A new DataStreamWriter for the file created from the specifed values.
Throws:
DataFileAlreadyExistsException - If the specified files exists and canot be overwritten.
See Also:
createDataWriter(String, String, String), FileTools.findUniqueFile(String, String, String, boolean)

createDataWriter

public static DataStreamWriter createDataWriter(java.lang.String dataFileDir,
                                                java.lang.String dataFileBaseName,
                                                java.lang.String dataFileExt)
Creates a new DataStreamWriter object for a unique file whose name is created on the basis of the specified base name, extension and directory as well as an optional timestamp and an optional counter to make the file name unique.
If despite of the unique file name an output stream cannot be open (this may happen with a small probability in the case of several competing processes) the semantics of this method are the same as for createDataWriter(File, boolean) (with overwrite = false).

This method uses the library method FileTools.findUniqueFile(String, String, String, boolean) for generating a unique file path (with alwaysUseTimestamp = false). The semantics are as follows:
1) A file name is created on the basis of the specified directory, base name and extension. (e.g. "directory/simulation.lgdat").
2) If the specified file name contains a substring that defines a timestamp marker (the string ""%ts""), the marker is replaced by a timestamp based on the current system time. If the specified file name does not contain a timestamp marker, no timespamp is inserted. Executed on 20 Jan 2008 at 18:30:15 the result may look like this: "directory/simulation.08.01.20-18.30.15.lgdat".
3) If no physical file with the resulting file name exists already, this file name is used. If a file with the resulting path exists, a counter is inserted just before the extension. The result may look like this: "directory/simulation.08.01.20-18.30.15(1).lgdat".
4) The uniqueness counter is increased (starting with 1) until the resulting file name does not describe a physical file that already exists.

Parameters:
dataFileDir - The directory where the data file will be created.
dataFileBaseName - The base name for the data file.
dataFileExt - The extension of the data file.
Returns:
A new DataStreamWriter for the file created from the specifed values.
Throws:
DataFileAlreadyExistsException - If the specified files exists and canot be overwritten.
See Also:
FileTools.findUniqueFile(String, String, String, boolean)

createDataWriter

public static DataStreamWriter createDataWriter(java.lang.String filePath,
                                                boolean overwrite)
Creates a new DataStreamWriter object for the specified file path.
If the file already exists, it may be overwritten if overwrite is true.
If a file output stream cannot be opened either becasue the file already exists and overwrite is false or for any other reason, the stream creation will be attempted again several times with a short random delay that increases after each attempt.
If after several attempts the file stream could not be opened, a DataFileAlreadyExistsException will be raised.
This is equivalent to createDataWriter(new File(filePath), overwrite).

Parameters:
filePath - Path of the file to which the new DataStreamWriter is to write its output.
overwrite - Whether to attempt overwriting the specified file it is exists.
Returns:
A new DataStreamWriter for the specified file.
Throws:
java.lang.NullPointerException - If the specified file is null.
DataFileAlreadyExistsException - If the specified files exists and canot be overwritten.

createDataWriter

public static DataStreamWriter createDataWriter(java.io.File file,
                                                boolean overwrite)
Creates a new DataStreamWriter object for the specified file.
If the file already exists, it may be overwritten if overwrite is true.
If a file output stream cannot be opened either becasue the file already exists and overwrite is false or for any other reason, the stream creation will be attempted again several times with a short random delay that increases after each attempt.
If after several attempts the file stream could not be opened, a DataFileAlreadyExistsException will be raised.

Parameters:
file - A file to which the new DataStreamWriter is to write its output.
overwrite - Whether to attempt overwriting the specified file it is exists.
Returns:
A new DataStreamWriter to the specified file.
Throws:
java.lang.NullPointerException - If the specified file is null.
DataFileAlreadyExistsException - If the specified files exists and canot be overwritten.

LiveGraph
data visualisation and analysis framework