Library (Apache Flex - FlexJS: Compiler: Parent 0.8.0-SNAPSHOT API)

java.lang.Object
- flex2.tools.oem.Library

All Implemented Interfaces:

Builder, Cloneable

Direct Known Subclasses:

BuilderLibrary
```
public class Library
extends Object
implements Builder, Cloneable
```
The Library class represents a SWC archive or a RSL. It implements the Builder interface which allows for building the library incrementally. The following example defines a SWC archive or RSL:
```
 Library lib = new Library();
 
```
You can add components to the Library object in the following ways:
```
 1. String              - Specify a fully-qualified name.
 2. File                - Specify a source file.
 3. VirtualLocalFile    - Specify an in-memory source object.
 4. URI                 - Specify a namespace URI.
 
```
To add resource bundles to the Library, you can use the addResourceBundle() method, as the following example shows:
```
 lib.addResourceBundle("mx.controls"));
 
```
To add archive files to the Library, you can use the addArchiveFile() method, as the following example shows:
```
 lib.addArchiveFile("defaults.css", new File("path1/myStyle.css"));
 
```
Before you can compile with a Library object, you must configure it. The following four methods are the most common methods you use to configure the Library object:
```
 1. setLogger()        - Use this to set a Logger so that the client can be notified of events that occurred during the compilation.
 2. setConfiguration() - Optional. Use this to specify compiler options.
 3. setOutput()        - Optional. Use this to specify an output file name.
 4. setDirectory()     - Optional. Use this to specify an RSL output directory.
 
```
You must implement the flex2.tools.oem.Logger interface and use the implementation as the Logger for the compilation. The following is an example Logger implementation:
```
 lib.setLogger(new flex2.tools.oem.Logger()
 {
     public void log(Message message, int errorCode, String source)
     {
         System.out.println(message);
     }
 });
 
```
To specify compiler options for the Library object, you must get a Configuration object that is populated with default values. Then, you set compiler options programmatically using methods of the Configuration class.
The setOutput() method lets you specify where the Library object writes the output to. If you call the setOutput() method, the build(boolean) method writes directly to the specified location; for example:
```
 lib.setOutput(new File("MyLib.swc"));
 lib.build(true);
 
```
If you do not call the setOutput() method, you can use the build(OutputStream, boolean) method. This requires that you provide a buffered output stream; for example:
```
 lib.build(new BufferedOutputStream(new FileOutputStream("MyLib.swc")), true);
 
```
The setDirectory() method lets you output RSLs to the specified directory; for example:
```
 lib.setDirectory(new File("dir1"));
 lib.build(true);
 
```
You can save the Library object compilation data for reuse. You do this using the save(OutputStream) method. Subsequent compilations can use the load(OutputStream) method to get the old data into the Library object; for example:
```
 lib.save(new BufferedOutputStream(new FileOutputStream("MyLib.incr")));
 
```
When a cache file (for example, MyLib.incr) from a previous compilation is available before the compilation, you can call the load(OutputStream) method before you call the build() method; for example:
```
 lib.load(new BufferedInputStream(FileInputStream("MyLib.incr")));
 lib.build(true);
 
```
The build(false) and build(OutputStream, false) methods always rebuild the library. The first time you build the Library object, the build(true)/build(OutputStream, true) methods do a complete build, which is equivalent to the build(false)/build(OutputStream, false) methods, respectively. After you call the clean() method, the Library object always does a full build.
The clean() method cleans up compilation data in the Library object the output file, if the setOutput() method was called.
You can use the Library class to build a library from a combination of source files in the file system and in-memory, dynamically-generated source objects. You must use the addComponent(VirtualLocalFile), addResourceBundle(VirtualLocalFile), and addArchiveFile(String, VirtualLocalFile) methods to use in-memory objects.
The Library class can be part of a Project.
Version:

2.0.1

Author:

Clement Wong

See Also:
Configuration, flex2.tools.oem.Project

Field Summary

Fields
Modifier and Type Field and Description

protected PathResolver resolver
- Fields inherited from interface flex2.tools.oem.Builder
  FAIL, LINK, OK, SKIP

Fields
Modifier and Type	Field and Description
`protected PathResolver`	`resolver`

Constructor Summary

Constructors
Constructor and Description

Library()
Constructor.

Constructors
Constructor and Description
`Library()` Constructor.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addArchiveFile(String name, File file)` Adds a file to this `Library` object.
`void`	`addArchiveFile(String name, VirtualLocalFile file)` Adds an in-memory source object to this `Library` object.
`void`	`addComponent(File includeSource)` Adds a component to this `Library` object.
`void`	`addComponent(String includeClass)` Adds a class, function, variable, or namespace to this `Library` object.
`void`	`addComponent(URI includeNamespace)` Adds a list of components to this `Library` object.
`void`	`addComponent(VirtualLocalFile includeSource)` Adds a component to this `Library` object.
`void`	`addResourceBundle(String resourceBundle)` Adds a resource bundle to this `Library` object.
`void`	`addStyleSheet(String name, File file)` Adds a CSS stylesheet to this `Library` object.
`void`	`addStyleSheet(String name, VirtualLocalFile file)` Adds an in-memory CSS stylesheet object to this `Library` object.
`long`	`build(boolean incremental)` Builds the object.
`long`	`build(OutputStream out, boolean incremental)` Builds the object.
`void`	`clean()` If you called the `setOutput()` method, this method deletes the `Application` or `Library` file.
`Library`	`clone()`
`protected int`	`compile(boolean incremental)` Compiles the `Library`.
`void`	`convertMessages(ProblemQuery pq)`
`ApplicationCache`	`getApplicationCache()` Returns the cache of sources in the source list and source path.
`Benchmark`	`getBenchmark()` Gets the overall performance data for the last build.
`HashMap<String,PerformanceData[]>`	`getCompilerBenchmarks()` Gets the performance data for each compiler phase for the last build.
`Configuration`	`getConfiguration()` Gets the compiler options for this object.
`Configuration`	`getDefaultConfiguration()` Gets the default compiler options.
`File`	`getDirectory()` Gets the RSL output directory.
`Logger`	`getLogger()` Gets the logger for this object.
`File`	`getOutput()` Gets the output destination.
`Report`	`getReport()` Reports information about the current compilation.
`LibraryCache`	`getSwcCache()` Get the cache of swcs in the library path.
`long`	`link(OutputStream output)`
`void`	`load(InputStream in)` Loads compilation data from a previous compilation.
`void`	`refreshLastModified()`
`void`	`removeAllArchiveFiles()` Removes all the archive files from this `Library` object.
`void`	`removeAllComponents()` Removes all the components from this `Library` object.
`void`	`removeAllResourceBundles()` Removes all the resource bundles from this `Library` object.
`void`	`removeAllStyleSheets()` Removes all the CSS stylesheets from this `Library` object.
`void`	`removeArchiveFile(String name)` Removes the specified file from this `Library` object.
`void`	`removeComponent(File includeSource)` Removes the specified component from this `Library` object.
`void`	`removeComponent(String includeClass)` Removes the specified component from this `Library` object.
`void`	`removeComponent(URI includeNamespace)` Removes the specified list of components from this `Library` object.
`void`	`removeComponent(VirtualLocalFile includeSource)` Removes the specified component from this `Library` object.
`void`	`removeResourceBundle(String resourceBundle)` Removes the specified resource bundle name from this `Library` object.
`void`	`removeStyleSheet(String name)` Removes the specified CSS stylesheet from this `Library` object.
`long`	`save(OutputStream out)` Saves the current compilation data.
`void`	`setApplicationCache(ApplicationCache applicationCache)` Sets the cache for sources in the source list and source path.
`void`	`setConfiguration(Configuration configuration)` Sets the compiler options for this object.
`void`	`setDirectory(File directory)` Sets the RSL output directory.
`void`	`setLogger(Logger logger)` Sets the logger for this object.
`void`	`setOutput(File output)` Sets the output destination.
`void`	`setPathResolver(PathResolver resolver)` Sets the path resolver for this object.
`void`	`setProgressMeter(ProgressMeter meter)` Sets the progress meter for this object.
`void`	`setSupportedFileExtensions(String mimeType, String[] extensions)` Sets the custom file extensions for this object.
`void`	`setSwcCache(LibraryCache libraryCache)` Set the cache for swcs in the library path.
`void`	`stop()` Stops the compilation.

Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - resolver
```
protected PathResolver resolver
```
- Constructor Detail
  - Library
```
public Library()
```
    Constructor.
- Method Detail
  - addComponent
```
public void addComponent(String includeClass)
```
    Adds a class, function, variable, or namespace to this Library object. This is the equilvalent of the include-classes option of the compc compiler.
    
    Parameters:
    includeClass - A fully-qualified name.
  - addComponent
```
public void addComponent(File includeSource)
```
    Adds a component to this Library object. This is the equilvalent of the include-sources option of the compc compiler.
    
    Parameters:
    includeSource - A source file.
  - addComponent
```
public void addComponent(VirtualLocalFile includeSource)
```
    Adds a component to this Library object. This is equilvalent to the include-sources option of the compc compiler.
    
    Parameters:
    includeSource - An in-memory source object.
  - addComponent
```
public void addComponent(URI includeNamespace)
```
    Adds a list of components to this Library object. This is equilvalent to the include-namespaces option of the compc compiler.
    
    Parameters:
    includeNamespace - A namespace URI.
  - removeComponent
```
public void removeComponent(String includeClass)
```
    Removes the specified component from this Library object. The name can be a class, a function, a variable, or a namespace.
    
    Parameters:
    includeClass - A fully-qualified name.
  - removeComponent
```
public void removeComponent(File includeSource)
```
    Removes the specified component from this Library object.
    
    Parameters:
    includeSource - A source file.
  - removeComponent
```
public void removeComponent(VirtualLocalFile includeSource)
```
    Removes the specified component from this Library object.
    
    Parameters:
    includeSource - An in-memory source object.
  - removeComponent
```
public void removeComponent(URI includeNamespace)
```
    Removes the specified list of components from this Library object. The input argument is a namespace URI.
    
    Parameters:
    includeNamespace - A namespace URI.
  - removeAllComponents
```
public void removeAllComponents()
```
    Removes all the components from this Library object.
  - addResourceBundle
```
public void addResourceBundle(String resourceBundle)
```
    Adds a resource bundle to this Library object. This is equilvalent to the include-resource-bundles option of the compc compiler.
    
    Parameters:
    resourceBundle - A resource bundle name.
  - removeResourceBundle
```
public void removeResourceBundle(String resourceBundle)
```
    Removes the specified resource bundle name from this Library object.
    
    Parameters:
    resourceBundle - A resource bundle name.
  - removeAllResourceBundles
```
public void removeAllResourceBundles()
```
    Removes all the resource bundles from this Library object.
  - addArchiveFile
```
public void addArchiveFile(String name,
                  File file)
```
    Adds a file to this Library object. This is equilvalent to the include-file option of the compc compiler.
    
    Parameters:
    name - The name in the archive.
    file - The file to be added.
  - addArchiveFile
```
public void addArchiveFile(String name,
                  VirtualLocalFile file)
```
    Adds an in-memory source object to this Library object. This is equilvalent to the include-file option of the compc compiler.
    
    Parameters:
    name - The name in the archive.
    file - The in-memory source object to be added.
  - removeArchiveFile
```
public void removeArchiveFile(String name)
```
    Removes the specified file from this Library object.
    
    Parameters:
    name - The name in the archive.
  - removeAllArchiveFiles
```
public void removeAllArchiveFiles()
```
    Removes all the archive files from this Library object.
  - addStyleSheet
```
public void addStyleSheet(String name,
                 File file)
```
    Adds a CSS stylesheet to this Library object. This is equilvalent to the include-stylesheet option of the compc compiler.
    
    Parameters:
    name - The name in the archive.
    file - The file to be added.
    Since:
    
    3.0
  - addStyleSheet
```
public void addStyleSheet(String name,
                 VirtualLocalFile file)
```
    Adds an in-memory CSS stylesheet object to this Library object. This is equilvalent to the include-stylesheet option of the compc compiler.
    
    Parameters:
    name - The name in the archive.
    file - The in-memory source object to be added.
    Since:
    
    3.0
  - removeStyleSheet
```
public void removeStyleSheet(String name)
```
    Removes the specified CSS stylesheet from this Library object.
    
    Parameters:
    name - The name in the archive.
    Since:
    
    3.0
  - removeAllStyleSheets
```
public void removeAllStyleSheets()
```
    Removes all the CSS stylesheets from this Library object.
    
    Since:
    
    3.0
  - setConfiguration
```
public void setConfiguration(Configuration configuration)
```
    Description copied from interface: Builder
    
    Sets the compiler options for this object. You use the getDefaultConfiguration() method to get a Configuration object.
    
    Specified by:
    
    setConfiguration in interface Builder
    
    Parameters:
    configuration - An instance of an object that implements the Configuration interface.
    See Also:
    Configuration
  - getDefaultConfiguration
```
public Configuration getDefaultConfiguration()
```
    Description copied from interface: Builder
    
    Gets the default compiler options. The default values are specified in the flex-config.xml file. You can override the default values by using methods of the Configuration interface.
    This method returns the default compiler options in new Configuration objects.
    
    Specified by:
    
    getDefaultConfiguration in interface Builder
    
    Returns:
    An instance of an object that implements the Configuration interface.
    See Also:
    Configuration
  - getCompilerBenchmarks
```
public HashMap<String,PerformanceData[]> getCompilerBenchmarks()
```
    Description copied from interface: Builder
    
    Gets the performance data for each compiler phase for the last build.
    
    Specified by:
    
    getCompilerBenchmarks in interface Builder
    
    Returns:
    A map of compiler phase to PerformanceData.
  - getBenchmark
```
public Benchmark getBenchmark()
```
    Description copied from interface: Builder
    
    Gets the overall performance data for the last build.
    
    Specified by:
    
    getBenchmark in interface Builder
    
    Returns:
    a Benchmark object.
  - getConfiguration
```
public Configuration getConfiguration()
```
    Description copied from interface: Builder
    
    Gets the compiler options for this object. Unlike the getDefaultConfiguration() method, this method returns null if the setConfiguration() method was not called.
    
    Specified by:
    
    getConfiguration in interface Builder
    
    Returns:
    An instance of an object that implements the Configuration interface.
    See Also:
    Configuration
  - setLogger
```
public void setLogger(Logger logger)
```
    Description copied from interface: Builder
    
    Sets the logger for this object. The compiler uses the logger to notify clients of events that occurred during the compilation.
    
    Specified by:
    
    setLogger in interface Builder
    
    Parameters:
    logger - An object that implements the Logger interface.
    See Also:
    Logger
  - getLogger
```
public Logger getLogger()
```
    Description copied from interface: Builder
    
    Gets the logger for this object. This method returns null if the setLogger() method was not called.
    
    Specified by:
    
    getLogger in interface Builder
    
    Returns:
    An object that implements the Logger interface.
    See Also:
    Logger
  - setSupportedFileExtensions
```
public void setSupportedFileExtensions(String mimeType,
                              String[] extensions)
```
    Description copied from interface: Builder
    Sets the custom file extensions for this object. For example:
```
 setSupportedFileExtensions(flex2.compiler.util.MimeMappings.MXML, new String[] {".foo"});
 
```
    This example instructs the compiler to treat files with the *.foo extension as MXML documents. The supported MIME types are specified in the flex2.compiler.util.MimeMappings class as constants.
    Specified by:
    
    setSupportedFileExtensions in interface Builder
    
    Parameters:
    mimeType - MIME type.
    extensions - An array of file extensions.
  - setOutput
```
public void setOutput(File output)
```
    Sets the output destination. This method is necessary if you use the build(boolean) method. If you use the build(OutputStream, boolean) method, there is no need to use this method.
    
    Parameters:
    output - An instance of the java.io.File class.
  - getOutput
```
public File getOutput()
```
    Gets the output destination. This method returns null if you did not call the setOutput() method.
    
    Specified by:
    
    getOutput in interface Builder
    
    Returns:
    An instance of the java.io.File class, or null if you did not call the setOutput() method.
  - setDirectory
```
public void setDirectory(File directory)
```
    Sets the RSL output directory.
    
    Parameters:
    directory - An RSL directory.
  - getDirectory
```
public File getDirectory()
```
    Gets the RSL output directory.
    
    Returns:
    A java.io.File, or null if you did not call the setDirectory() method.
  - setProgressMeter
```
public void setProgressMeter(ProgressMeter meter)
```
    Description copied from interface: Builder
    
    Sets the progress meter for this object. This method is optional. You can set a progress meter so that it receives periodic updates during the compilation.
    
    Specified by:
    
    setProgressMeter in interface Builder
    
    Parameters:
    meter - An object that implements the ProgressMeter interface.
    See Also:
    ProgressMeter
  - setPathResolver
```
public void setPathResolver(PathResolver resolver)
```
    Description copied from interface: Builder
    
    Sets the path resolver for this object. This method is optional.
    
    Specified by:
    
    setPathResolver in interface Builder
    
    Parameters:
    resolver - A path resolver
    See Also:
    PathResolver
  - build
```
public long build(boolean incremental)
           throws IOException
```
    Description copied from interface: Builder
    
    Builds the object. If the incremental input argument is false, this method recompiles all parts of the object. If the incremental input argument is true, this method compiles only the parts of the object that have changed since the last compilation.
    You must call the setOutput() method before calling this method. The result is saved to the location specified by the getOutput() method. If there is no output destination specified, this method does nothing and returns 0.
    
    Specified by:
    
    build in interface Builder
    
    Parameters:
    incremental - If true, build incrementally; if false, rebuild.
    
    Returns:
    The number of bytes written out.
    
    Throws:
    
    IOException - Thrown when an I/O error occurs during compilation.
    See Also:
    Application, Library
  - build
```
public long build(OutputStream out,
         boolean incremental)
           throws IOException
```
    Description copied from interface: Builder
    
    Builds the object. If the incremental input argument is false, this method recompiles all parts of the object. If the incremental input argument is true, this method compiles only the parts of the object that have changed since the last compilation.
    This method only outputs to the specified OutputStream. For better performance, the OutputStream should be buffered. This method does not output to the destination specified by the setOutput() method.
    
    Specified by:
    
    build in interface Builder
    
    Parameters:
    out - The OutputStream.
    incremental - If true, build incrementally; if false, rebuild.
    
    Returns:
    The number of bytes written out. This method returns 0 if the object fails to compile.
    
    Throws:
    
    IOException - Thrown when an I/O error occurs during compilation.
  - stop
```
public void stop()
```
    Description copied from interface: Builder
    
    Stops the compilation. If the client runs the compiler in a background thread, it can use this method to stop the compilation. The compiler does not stop immediately, but stops the compilation when it reaches a stable state.
    
    Specified by:
    
    stop in interface Builder
  - clean
```
public void clean()
```
    Description copied from interface: Builder
    
    If you called the setOutput() method, this method deletes the Application or Library file. Calls to the build() method trigger a full recompilation.
    The clean() method does not remove compiler options or reset the output location.
    
    Specified by:
    
    clean in interface Builder
  - load
```
public void load(InputStream in)
          throws IOException
```
    Description copied from interface: Builder
    
    Loads compilation data from a previous compilation. This method is usually called before the build() method.
    
    Specified by:
    
    load in interface Builder
    
    Parameters:
    in - The InputStream.
    
    Throws:
    
    IOException - Thrown when an I/O error occurs while loading the compilation data.
  - save
```
public long save(OutputStream out)
          throws IOException
```
    Description copied from interface: Builder
    
    Saves the current compilation data. This method is usually called after the build() method.
    Do not use this to create a SWF or SWC file. Use the build() method instead.
    
    Specified by:
    
    save in interface Builder
    
    Parameters:
    out - The OutputStream.
    
    Returns:
    The number of bytes written out.
    
    Throws:
    
    IOException - Thrown when an I/O error occurs while saving the compilation data.
  - getReport
```
public Report getReport()
```
    Description copied from interface: Builder
    Reports information about the current compilation. This method returns null if you have not yet called the build(boolean), build(OutputStream, boolean), or compile(boolean) methods.
    The Report object includes the following information:
    1. Number of source files used in the compilation.
    2. The location of the source files.
    3. Number of asset files that are embedded in the Application or Library.
    4. The location of the asset files.
    5. The dependencies of the source files.
    You must call the getReport() method to get a new report after each call to the build() method.
    Specified by:
    
    getReport in interface Builder
    
    Returns:
    An object that implements the Report interface.
  - compile
```
protected int compile(boolean incremental)
```
    Compiles the Library. This method does not link the Library.
    
    Parameters:
    incremental - If true, build incrementally; if false, rebuild.
    
    Returns:
    Builder.OK if this method call resulted in compilation of some/all parts of the application; Builder.LINK if this method call did not compile anything in the application but advise the caller to link again; Builder.SKIP if this method call did not compile anything in the application; Builder.FAIL if this method call encountered errors during compilation.
  - link
```
public long link(OutputStream output)
```
  - getApplicationCache
```
public ApplicationCache getApplicationCache()
```
    Returns the cache of sources in the source list and source path. After building this Application object, the cache may be used to compile another Application object with common sources.
    
    Returns:
    The active cache. May be null.
    Since:
    
    4.5
  - setApplicationCache
```
public void setApplicationCache(ApplicationCache applicationCache)
```
    Sets the cache for sources in the source list and source path. After compiling an Application object, the cache may be reused to build another Application object with common sources.
    
    Specified by:
    
    setApplicationCache in interface Builder
    
    Parameters:
    applicationCache - A reference to the application cache.
    Since:
    
    4.5
  - getSwcCache
```
public LibraryCache getSwcCache()
```
    Get the cache of swcs in the library path. After building this Application object the cache may be saved and used to compile another Application object that uses the same library path.
    
    Returns:
    The active cache. May be null.
    Since:
    
    3.0
  - setSwcCache
```
public void setSwcCache(LibraryCache libraryCache)
```
    Set the cache for swcs in the library path. After compiling an Application object the cache may be reused to build another Application object that uses the same library path.
    
    Specified by:
    
    setSwcCache in interface Builder
    
    Parameters:
    swcCache - A reference to an allocated swc cache.
    Since:
    
    3.0
  - clone
```
public Library clone()
```
    Overrides:
    
    clone in class Object
  - refreshLastModified
```
public void refreshLastModified()
```
  - convertMessages
```
public void convertMessages(ProblemQuery pq)
```

Class Library

Field Summary

Fields inherited from interface flex2.tools.oem.Builder

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

resolver

Constructor Detail

Library

Method Detail

addComponent

addComponent

addComponent

addComponent

removeComponent

removeComponent

removeComponent

removeComponent

removeAllComponents

addResourceBundle

removeResourceBundle

removeAllResourceBundles

addArchiveFile

addArchiveFile

removeArchiveFile

removeAllArchiveFiles

addStyleSheet

addStyleSheet

removeStyleSheet

removeAllStyleSheets

setConfiguration

getDefaultConfiguration

getCompilerBenchmarks

getBenchmark

getConfiguration

setLogger

getLogger

setSupportedFileExtensions

setOutput

getOutput

setDirectory

getDirectory

setProgressMeter

setPathResolver

build

build

stop

clean

load

save

getReport

compile

link

getApplicationCache

setApplicationCache

getSwcCache

setSwcCache

clone

refreshLastModified

convertMessages