com.cleancode.format
Class JSArchive

java.lang.Object
  com.cleancode.format.JSArchive

public class JSArchive
extends Object

Creates a JavaScript archive that consolidates and compresses a collection of JavaScript files. There are three considerations to using such a tool.

• You wish to improve throughput by reducing the number of server interactions. JSArchive reduces your multiple JavaScript file fetches down to a single one. [Consolidation]
• You wish to improve throughput by reducing the amount of data sent for a page. JSArchive reduces the size of your JavaScript files significantly (30 to 70% is common, depending on your content). [Compression]
• You wish to protect your intellectual property rights. JSArchive provides code obfuscation: that is, by removing extraneous whitespace (and therefore visual code structure) as well as comments throughout your code, it becomes much more difficult for a human reader to comprehend.

The default behavior is to consolidate without compression. Use the -c option to compress, or to promote real obfuscation, use -c and -l, the latter adding line break suppression so that each file becomes a single line of code in the archive.

When you have enabled compression mode and/or line break suppression mode, you may selectively choose to leave certain files with line breaks or certain files completely uncompressed (for example, if you wish to add a title block in a comment at the top of your archive file). Precede any file you wish to exclude from being compressed with the nc: pseudo-protocol tag, as in nc:myfile.txt. Similarly, precede any file you wish to retain line breaks with the nC: pseudo-protocol tag. The combination of -c and -l (or -cl of course) provides the most compression but may run into issues with certain JavaScript constructs. When you have a "problem" file, back out the optimization for just that file by first trying nC:file to retain its line breaks. If for whatever reason you still have JavaScript problems, then you can back out further using nc:file, removing compression and retaining line breaks just for that file.

If you specify an archive file (rather than sending the archive to stdout) JSArchive will only rebuild the archive if needed, i.e. if one or more of the dependent files is newer than the archive file. This is a useful optimization most of the time--the exception is when you change your command-line (for instance, adding new files or changing compression on existing files). In that case simply remove the archive file so it will be regenerated.

This utility may be invoked as a standalone tool or as a library component. Normal operation will operate silently. Used as a library component, the calling program must handle any exceptions as needed. Used as a standalone tool, you may enable verbose console output with the -v command-line argument. In case of error, for example, JSArchive will display the first error found, along with a count of errors. Invoking in either fashion, you also get a separate log file that details the construction of the archive. If you use the -o command-line argument (or the setFilename method) to specify an archive file, the log file is created in the same directory as the archive; its name will be the same as the archive name with LOG_FILE_EXT appended. If your archive goes to stdout, on the other hand, the log will be named DEFAULT_LOG (plus the same extension LOG_FILE_EXT) in the current directory.

Since:

CleanCode 0.9

Version:

$Revision: 23 $

Author:

Michael Sorens

Nested Class Summary

class

JSArchive.JSCompactor Compacts a series of text strings, discarding any unnecessary whitespace as well as all comments.

Field Summary

static String	ARCHIVE_ELEM_MARKER Notation prepended to each file in the archive, allowing for future scanning to identify archive contents.
static String	DEFAULT_LOG Default log file base name when archive generated on stdout.
static String	LOG_FILE_EXT Log file extension.
static String	VERSION Current version of this class.

Constructor Summary

JSArchive()
Creates a new JSArchive to compress a set of JavaScript files.

Method Summary

void	generateArchive(String[] args) Processes a list of files into the archive.
int	getErrCount() Returns the count of errors, if any.
boolean	isContentsMode() Identifies whether contentsMode has been set.
static void	main(String[] args) Command-line support to create a JavaScript archive.
void	setCompactMode(boolean compactMode) Specifies whether generated archive should be compacted or not.
void	setContentsMode(boolean contentsMode) Selects table of contents display mode.
void	setDisplayArgs(String[] displayArgs) Specifies whether command-line should be emitted as a comment in the archive.
void	setFilename(String name) Specifies a target file name for the archive.
void	setOneLineMode(boolean oneLineMode) Sets mode for compacting a file by retaining line breaks or not.
void	setVerbose(boolean verbose) Specifies verbose console output option.
void	showContents() Displays contents of a previously created archive.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LOG_FILE_EXT

public static final String LOG_FILE_EXT

Log file extension.

See Also:

Constant Field Values

DEFAULT_LOG

public static final String DEFAULT_LOG

Default log file base name when archive generated on stdout.

See Also:

Constant Field Values

ARCHIVE_ELEM_MARKER

public static final String ARCHIVE_ELEM_MARKER

Notation prepended to each file in the archive, allowing for future scanning to identify archive contents.

See Also:

Constant Field Values

VERSION

public static final String VERSION

Current version of this class.

Constructor Detail

JSArchive

public JSArchive()

Creates a new JSArchive to compress a set of JavaScript files.

Method Detail

isContentsMode

public boolean isContentsMode()

Identifies whether contentsMode has been set.

Returns:

Returns whether mode is generate archive or display contents.

setFilename

public void setFilename(String name)

Specifies a target file name for the archive. If not invoked, output is sent to STDOUT for archive generation. For archive contents display, this method must be invoked.

Parameters:

name - archive name

setCompactMode

public void setCompactMode(boolean compactMode)

Specifies whether generated archive should be compacted or not. If false, the archive is then just a concatenation of the input files.

Parameters:

compactMode - true value indicates to compact

setContentsMode

public void setContentsMode(boolean contentsMode)

Selects table of contents display mode. Displays the contents of a specified archive file.

Parameters:

contentsMode - true value displays contents of archive

setOneLineMode

public void setOneLineMode(boolean oneLineMode)

Sets mode for compacting a file by retaining line breaks or not.

Parameters:

oneLineMode - If true, removes line breaks within a file.

setVerbose

public void setVerbose(boolean verbose)

Specifies verbose console output option. If true, progress of the archive generation is reported to stderr.

Parameters:

verbose - true value indicates to display output on stderr

setDisplayArgs

public void setDisplayArgs(String[] displayArgs)

Specifies whether command-line should be emitted as a comment in the archive. If not invoked, command-line will be omitted from comment in the archive.

Parameters:

displayArgs - array of command line arguments

getErrCount

public int getErrCount()

Returns the count of errors, if any. Errors include attempting to add the archive file to itself, and any I/O errors during processing (typically files not found).

Returns:

count of errors

showContents

public void showContents()
                  throws IOException

Displays contents of a previously created archive. During archive creation, each included file's header included an archive marker (ARCHIVE_ELEM_MARKER) that is used to identify the individual components.

Throws:

IOException - on any file problems

generateArchive

public void generateArchive(String[] args)
                     throws IOException

Processes a list of files into the archive. The file begins with a preamble that specifies the archive name, the creation date, the name and version of the generator (JSArchive), and the command-line used to generate the archive. Example:

 //////////////////////////////////////////////////////////////////////
 // Archive: ../../../bkmk/MyBkmkFiles/BkArchive.js
 // Created: Mon Aug 30 15:32:08 PDT 2004
 // Generator: JSArchive [1.15]
 //
 // The command line arguments to generate this file:
 // com.cleancode.format.JSArchive -c -o ../../../bkmk/MyBkmkFiles/BkArchive.js
   ../netscape/sniffer.js ../webmonkey/parseURL.js ../cleancode/Util/Version.js... 
 //
 // This file was generated automatically and should not be edited manually.
 //////////////////////////////////////////////////////////////////////
 

Each file within the archive, then, is preceded with a short header comment including the original file name, the compression factor and a time stamp. Additionally, a marker (ARCHIVE_ELEM_MARKER) is inserted so that running the -t option to JSArchive can display the contents of the archive. You may add either local files (via local path name) or remote files (via URL).

JSArchive uses several nested classes to parcel out the work. JSReader will read each file and in turn invoke JSCompactor to compact each one. JSClassScanner is an experimental component that tries to add some additional information about the class structure in the log file. It does not interfere with the performance of the compression or consolidation at all.

Note that any parsing exceptions (notably unterminated strings) will output the original line unchanged with a brief comment tacked on the end.

Parameters:

args - list of names of local files or URLs to process.

Throws:

IOException - on any file problems

main

public static void main(String[] args)

Command-line support to create a JavaScript archive. Invoke with no arguments to see this list of command-line options:

• -c -- compacts files while archiving, removing comments and whitespace
• -v -- verbose (displays info to stderr while processing)
• -d -- omit displaying argument list as a comment in archive
• -l -- sets line-break suppression mode (removes breaks within each file)
• -t -- display table of contents of existing archive (requires -f)
• -f -- output to archive file rather than stdout

Parameters:

args - the command line arguments