sears.file
Class SubtitleFile

java.lang.Object
  extended by sears.file.SubtitleFile
Direct Known Subclasses:
SrtFile, SsaFile, SubFile

public abstract class SubtitleFile
extends java.lang.Object

Class SubtitleFile.
Summary:
This class represents a subtitle file. It provides facilities on subtitles, as delay, resynchro. It must be specialized to the subtitle file type you want to open.
You would have to use the getInstance(File, ArrayList, String) static method for this


Field Summary
static java.lang.String[] BASIC_CHARSETS
          Represents an array of charsets that Sears can use to parse a file if an error occurs with the default one
static java.lang.String DEFAULT_CHARSET
          The default charset that Sears use to parse a subtitle file: "ISO-8859-1"
protected  java.io.File file
          The system File that contains the file
protected  boolean fileChanged
          A boolean to know if file has changed
protected  java.util.ArrayList<Subtitle> subtitleList
          The ArrayList of subtitles found
protected  java.io.File temporaryFile
          The temporary file
 
Constructor Summary
SubtitleFile()
          Constructor SubtitleFile.
SubtitleFile(java.io.File _file, java.util.ArrayList<Subtitle> _subtitlesList)
          Constructor SubtitleFile.
SubtitleFile(java.io.File _file, java.util.ArrayList<Subtitle> _subtitlesList, java.lang.String charset)
          Constructor SubtitleFile.
SubtitleFile(java.lang.String fileToOpen, java.util.ArrayList<Subtitle> _subtitlesList)
          Constructor SubtitleFile.
 
Method Summary
 void accentRepair(int[] selectedIndex)
          Method accentRepair.
 void addFakeSub()
          Method addFakeSub.
 void addSubtitle(Subtitle subtitle)
          Method addSubtitle.
 void addSubtitle(Subtitle subtitle, boolean updateNumber)
          Method addSubtitle.
 void append(SubtitleFile subtitleFileToAppend, int delay)
          Method append.
 void delay(int delay)
          Method delay.
 void delay(int[] indexToDelay, int delay)
          Method delay.
 void delay(int beginIndex, int endIndex, int delay)
          Method delay.
abstract  java.lang.String extension()
          Returns the extension file
 void fileChanged()
          Method fileChanged
Summary:
Set the fileChanged status flag to true.
protected static java.lang.String getANonNullCharset(java.lang.String charset)
          Returns charset if it is non null, else DEFAULT_CHARSET is returned
 java.lang.String getCharset()
          Returns the charset used for write and read operations
 java.io.File getContentDirectory()
          Method getContentDirectory.
 java.io.File getFile()
          Method getFile.
static SubtitleFile getInstance(java.io.File file, java.util.ArrayList<Subtitle> subtitleList)
          Same that getInstance(File, ArrayList, String).
static SubtitleFile getInstance(java.io.File file, java.util.ArrayList<Subtitle> subtitleList, java.lang.String charset)
          Returns an instance of a SubtitleFile implementation class which represents the subtitle type of the given java.io.File object.
static SubtitleFile getInstance(java.io.File file, java.util.ArrayList<Subtitle> subtitleList, java.lang.String charset, boolean useEmptyConstructor)
          Returns an instance of a SubtitleFile implementation class which represents the subtitle type of the given java.io.File object.
static java.lang.String getLineSeparator()
          Returns the line separator (end of line) to use (depends to the user choice).
protected abstract  SubtitleFile getNewInstance()
          Method getNewInstance.
 Subtitle getSubtitleAtDate(int date)
          Method getSubtitleIndex.
 java.util.ArrayList<Subtitle> getSubtitleList()
          Method getSubtitleList.
 java.util.ArrayList<Subtitle> getSubtitleListClone()
          Method getSubtitleListClone.
protected  java.util.ArrayList<Subtitle> getSubtitles()
          Method getSubtitles.
 java.io.File getTemporaryFile()
          Method getTemporaryFile.
 void htmlRepair(int[] selectedIndex)
          Method htmlRepair.
 boolean isFileChanged()
           
 void magicResynchro()
          Method magicResynchro.
 boolean mixWithAnotherSubtitleFile(SubtitleFile theOtherSubtitleFile, boolean keepSubtitles)
          Mix subtitle files keeps times and copy subtiles from another subtitle file.
 void normalizeDuration(int[] indexToNormalize, int minDuration, int maxDuration)
          Method normalizeDuration.
 void normalizeDuration(int minDuration, int maxDuration)
          Method normalizeDuration.
 void orderRepair()
          Method orderRepair.
protected abstract  void parse()
          Method parse.
 void resynchro(int[] result)
          Method resynchro.
 void setCharset(java.lang.String charset)
          Changes the charset, if a non null value is given, DEFAULT_CHARSET is set as the used charset
 void setFile(java.io.File file)
          Method setFile.
 void setSubtitleList(java.util.ArrayList<Subtitle> subtitleList)
          Method setSubtitleList.
protected  void shiftToZero()
          Method shiftToZero.
 SubtitleFile[] split(java.io.File[] destinationFiles, int subtitleIndex, int secondPartDelay)
          Method split.
static int stringToTime(java.lang.String time)
          Method stringToTime.
 void timeRepair()
          Method timeRepair.
static java.lang.String timeToString(int milliseconds)
          Method timeToString.
abstract  void writeToFile(java.io.File fileToWrite)
          Method writeToFile.
abstract  void writeToTemporaryFile()
          Method writeToTemporaryFile.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

file

protected java.io.File file
The system File that contains the file


subtitleList

protected java.util.ArrayList<Subtitle> subtitleList
The ArrayList of subtitles found


fileChanged

protected boolean fileChanged
A boolean to know if file has changed


temporaryFile

protected java.io.File temporaryFile
The temporary file


DEFAULT_CHARSET

public static final java.lang.String DEFAULT_CHARSET
The default charset that Sears use to parse a subtitle file: "ISO-8859-1"

See Also:
Constant Field Values

BASIC_CHARSETS

public static final java.lang.String[] BASIC_CHARSETS
Represents an array of charsets that Sears can use to parse a file if an error occurs with the default one

Constructor Detail

SubtitleFile

public SubtitleFile()
Constructor SubtitleFile.
Summary:
Constructor of the class. Beware not to use this file directly, because it does contains no ST. You will have to fill the list of ST, and save the File first.


SubtitleFile

public SubtitleFile(java.lang.String fileToOpen,
                    java.util.ArrayList<Subtitle> _subtitlesList)
             throws FileConversionException
Constructor SubtitleFile.
Summary:
Constructor of the class.

Parameters:
fileToOpen - The (String) path to file to open.
_subtitlesList - The (ArrayList) List of subtitles.
Throws:
FileConversionException - if a limitation when reading the file appears

SubtitleFile

public SubtitleFile(java.io.File _file,
                    java.util.ArrayList<Subtitle> _subtitlesList)
             throws FileConversionException
Constructor SubtitleFile.
Summary:
Constructor of the class.

Parameters:
_file - The (File) file to open.
_subtitlesList - The (ArrayList) List of subtitles.
Throws:
FileConversionException - if a limitation when reading the file appears

SubtitleFile

public SubtitleFile(java.io.File _file,
                    java.util.ArrayList<Subtitle> _subtitlesList,
                    java.lang.String charset)
             throws FileConversionException
Constructor SubtitleFile.
Summary:
Constructor of the class.

Parameters:
_file - The (File) file to open.
_subtitlesList - The (ArrayList) List of subtitles.
charset - The charset to use during operations on the file ...
Throws:
FileConversionException - if a limitation when reading the file appears
Method Detail

getANonNullCharset

protected static java.lang.String getANonNullCharset(java.lang.String charset)
Returns charset if it is non null, else DEFAULT_CHARSET is returned

Parameters:
charset - the charset to test
Returns:
DEFAULT_CHARSET or charset if it is non null

getCharset

public java.lang.String getCharset()
Returns the charset used for write and read operations

Returns:
the charset used by this

setCharset

public void setCharset(java.lang.String charset)
Changes the charset, if a non null value is given, DEFAULT_CHARSET is set as the used charset

Parameters:
charset - the new charset to use

getLineSeparator

public static java.lang.String getLineSeparator()
Returns the line separator (end of line) to use (depends to the user choice).
By default the system one is return.

Returns:
a string that denoted a line separator

extension

public abstract java.lang.String extension()
Returns the extension file

Returns:
the extension file

parse

protected abstract void parse()
                       throws FileConversionException
Method parse.
Summary:
This method parse the current file, and construct the subtitleList.

Throws:
FileConversionException - if a limitation when reading the file appears

getContentDirectory

public java.io.File getContentDirectory()
Method getContentDirectory.
Summary:
This method return the file's parent folder.

Returns:
(File) The parent of the current file.

getFile

public java.io.File getFile()
Method getFile.
Summary:
Return the current file.

Returns:
(File) The current file.

getTemporaryFile

public java.io.File getTemporaryFile()
Method getTemporaryFile.
Summary:
Return the temporary file.

Returns:
(File) The temporary file.

timeToString

public static java.lang.String timeToString(int milliseconds)
Method timeToString.
Summary:
This method transform a number of milliseconds in a string representation.

Parameters:
milliseconds - The number of milliseconds to transform
Returns:
(String) The corresponding String representation of the number of milliseconds.

stringToTime

public static int stringToTime(java.lang.String time)
                        throws java.lang.NumberFormatException
Method stringToTime.
Summary:
Return the number of miliseconds that correspond to the given String time representation.

Parameters:
time - The string srt time representation.
Returns:
(int) The corresponding number of miliseconds.
Throws:
java.lang.NumberFormatException - if there's a time error

writeToFile

public abstract void writeToFile(java.io.File fileToWrite)
                          throws FileConversionException
Method writeToFile.
Summary:
Use this method to write subtitle file to the given File.

Parameters:
fileToWrite - The File to write the file.
Throws:
FileConversionException

writeToTemporaryFile

public abstract void writeToTemporaryFile()
Method writeToTemporaryFile.
Summary:
Use this method to write subtitle file to the temporary File.


addFakeSub

public void addFakeSub()
Method addFakeSub.
Summary:
Use this method to create an empty subtitle file.


delay

public void delay(int beginIndex,
                  int endIndex,
                  int delay)
Method delay.
Summary:
Apply a delay on the given range subtitles.

Parameters:
beginIndex - The first index to begin delay.
endIndex - The last index to put a delay
delay - The delay to Apply.

delay

public void delay(int[] indexToDelay,
                  int delay)
Method delay.
Summary:
Delay a list of subtitles, idetified by their index.

Parameters:
indexToDelay - The array of subtitle's index to be delayed.
delay - The delay to apply.

delay

public void delay(int delay)
Method delay.
Summary:
Use this method to delay whole file.

Parameters:
delay - The delay to apply.

normalizeDuration

public void normalizeDuration(int minDuration,
                              int maxDuration)
Method normalizeDuration.
Summary:
This method permits to normalize the subtitle duration for whole file. It ensures that subtitle display duration is between given minDuration, and maxDuration. It raise or lower it to fit in the interval. It takes care that subtitle do not ends before the start of its follower. If minDuration equals to -1, it does not checks the minDuration. If maxDuration equals to -1, it does not checks the maxDuration.

Parameters:
minDuration - The min duration to ensure.
maxDuration - The max duration to ensure.

normalizeDuration

public void normalizeDuration(int[] indexToNormalize,
                              int minDuration,
                              int maxDuration)
Method normalizeDuration.
Summary:
This method permits to normalize the subtitle duration for given subtitle indexes. It ensures that subtitle display duration is between given minDuration, and maxDuration. It raise or lower it to fit in the interval. It takes care that subtitle do not ends before the start of its follower. If minDuration equals to -1, it does not checks the minDuration. If maxDuration equals to -1, it does not checks the maxDuration. If given indexes array is empty, it normalizes the whole file.

Parameters:
indexToNormalize - The array of subtitle index to be normalized.
minDuration - The min duration to ensure.
maxDuration - The max duration to ensure.

resynchro

public void resynchro(int[] result)
Method resynchro.
Summary:
Use this method to apply a resynchronisation.

Parameters:
result - The resynchro parameter, an int array organized like this: [0]:The source 1 [1]:The destination 1 [2]:The source 2 [3]:The destination 2

setFile

public void setFile(java.io.File file)
Method setFile.
Summary:
Set the file to the given file.

Parameters:
file - The file to set.

addSubtitle

public void addSubtitle(Subtitle subtitle)
Method addSubtitle.
Summary:
Add a subtitle to subtitle list. It may update the given subtitle number if needed.

Parameters:
subtitle - The Subtitle to add to the file.

addSubtitle

public void addSubtitle(Subtitle subtitle,
                        boolean updateNumber)
Method addSubtitle.
Summary:
Add a subtitle to subtitle list, recomputing its sequence number.

Parameters:
subtitle - The Subtitle to add to the file.
updateNumber - A boolean, true if want to update the number with its index. False not to update it.

split

public SubtitleFile[] split(java.io.File[] destinationFiles,
                            int subtitleIndex,
                            int secondPartDelay)
Method split.
Summary:
This method split the subtitle file in two part at the given subtitle index. The two part will be saved in the given destination files, and a delay will be applied to the second part.

Parameters:
destinationFiles - The File[] where to save the two parts of the file.
subtitleIndex - The int subtitle index, from wich create the second part of the subtitle.
secondPartDelay - The int initial delay to apply to the second part.
Returns:
an array of two SubtitleFile object

shiftToZero

protected void shiftToZero()
Method shiftToZero.
Summary:
This method delays the subtitles, so the first one appears at time 0:00:00.000


getNewInstance

protected abstract SubtitleFile getNewInstance()
Method getNewInstance.
Summary:
This method should return a new instance of the current SubtitleFile class.

Returns:
SubtitleFile A new instance of the current SubtitleFile class.

append

public void append(SubtitleFile subtitleFileToAppend,
                   int delay)
Method append.
Summary:
Use this method to append a Subtitle file, to the current one. Using the given delay before last ST of current one and first ST of the one to append.

Parameters:
subtitleFileToAppend - The SubtitleFile subtitle file to append.
delay - The int delay to use.

getSubtitles

protected java.util.ArrayList<Subtitle> getSubtitles()
Method getSubtitles.
Summary:
return the subtitle list.

Returns:
ArrayList The subtitle list.

isFileChanged

public boolean isFileChanged()
Returns:
Returns the fileChanged.

fileChanged

public void fileChanged()
Method fileChanged
Summary:
Set the fileChanged status flag to true.


accentRepair

public void accentRepair(int[] selectedIndex)
Method accentRepair.
Summary:
This method is called when user want to remove the accents and special characters from the given index. If no index is precised, it will remove accents from all the Subtitles.

Parameters:
selectedIndex - The index to remove the accents.

htmlRepair

public void htmlRepair(int[] selectedIndex)
Method htmlRepair.
Summary:
This method is called when user want to remove the htmls. If no index is precised, it will remove html tags from all the Subtitles.

Parameters:
selectedIndex - The index to remove the accents.

timeRepair

public void timeRepair()
Method timeRepair.
Summary:
This method is called when user want to time repair. It will correct the time superposition problem. When subtitle ends after next ST start time.


orderRepair

public void orderRepair()
Method orderRepair.
Summary:
This method is called when user want to repair the order of the subtitle file. It will check chronology, order ST's with their start time, and finally fix ST's numbers.


getSubtitleAtDate

public Subtitle getSubtitleAtDate(int date)
Method getSubtitleIndex.
Summary:
This method is used to know the subtitle that should be active at the given date.

Parameters:
date - The date (in milliseconds).
Returns:
Subtitle The subtitle.

magicResynchro

public void magicResynchro()
Method magicResynchro.
Summary:
This method permits to perform a magic resynchro, using the defined anchors.


mixWithAnotherSubtitleFile

public boolean mixWithAnotherSubtitleFile(SubtitleFile theOtherSubtitleFile,
                                          boolean keepSubtitles)
Mix subtitle files keeps times and copy subtiles from another subtitle file.
Mix subtitle files keeps subtitles and copy times from another subtitke file.
This method only works with two subtitle file with the same numer of subtitles

Parameters:
theOtherSubtitleFile - a SubtitleFile object
keepSubtitles - true, the subtitles are kept, false the times are kept
Returns:
true if this are changed, false if not

getInstance

public static SubtitleFile getInstance(java.io.File file,
                                       java.util.ArrayList<Subtitle> subtitleList,
                                       java.lang.String charset,
                                       boolean useEmptyConstructor)
                                throws FileConversionException,
                                       java.lang.Exception
Returns an instance of a SubtitleFile implementation class which represents the subtitle type of the given java.io.File object.
The class must be in the same package of the SubtitleFile class an its name must be format like: "Fileextension" + "File"
Example: for srt file, SrtFile)

Parameters:
file - the subtitle file
subtitleList - the subtitles list
useEmptyConstructor - True if you want to call the empty constructor of the instance. false If you want the full constructor of subtitleFile to be called (will parse the file)
Returns:
an instance of a SubtitleFile implementation class, null if an error occurs
Throws:
FileConversionException - if a limitation when reading the file appears
java.lang.Exception - // --temporary-- //

getInstance

public static SubtitleFile getInstance(java.io.File file,
                                       java.util.ArrayList<Subtitle> subtitleList,
                                       java.lang.String charset)
                                throws FileConversionException,
                                       java.lang.Exception
Returns an instance of a SubtitleFile implementation class which represents the subtitle type of the given java.io.File object.
The class must be in the same package of the SubtitleFile class an its name must be format like: "Fileextension" + "File"
Example: for srt file, SrtFile)

Parameters:
file - the subtitle file
subtitleList - the subtitles list
Returns:
an instance of a SubtitleFile implementation class, null if an error occurs
Throws:
FileConversionException - if a limitation when reading the file appears
java.lang.Exception - // --temporary-- //

getInstance

public static SubtitleFile getInstance(java.io.File file,
                                       java.util.ArrayList<Subtitle> subtitleList)
                                throws FileConversionException,
                                       java.lang.Exception
Same that getInstance(File, ArrayList, String).
Charset is set to the default one.

Parameters:
file - the subtitle file
subtitleList - the subtitle list to fill
Returns:
the new created SubtitleFile object
Throws:
FileConversionException - if an error occurs
java.lang.Exception - if an untraitable error occurs [to solved]

getSubtitleList

public java.util.ArrayList<Subtitle> getSubtitleList()
Method getSubtitleList.
Summary:
Return the subtitleList.

Returns:
the subtitleList

setSubtitleList

public void setSubtitleList(java.util.ArrayList<Subtitle> subtitleList)
Method setSubtitleList.
Summary:
Set the subtitleList.

Parameters:
subtitleList - the subtitleList to set

getSubtitleListClone

public java.util.ArrayList<Subtitle> getSubtitleListClone()
Method getSubtitleListClone.
Summary:
returns a clone of the subtitle list. All the Subtitles are cloned.

Returns:
(ArrayList) A clone of the subtitle list. All Subtitles are cloned.