Flex compiler API指南（第一章）

第一章 介绍

        本文介绍了 Adobe(R) Flex(TM) compiler API, 它是OEM Kit的一部分。文章的“快速开始”部分包含了一个充分的例子，让您能够轻松上路。

关于Flex compiler API

        Flex complier API是Flex OEM Kit的一部分。它可以让您使用JAVA应用程序去编译Flex应用程序。您也可以在内存中建立应用程序并编译它们，使其生成SWF文件，甚至不用在磁盘上建立MXML文件。此外，Flex  compiler API 能够为您输出该Flex应用程序的关联报告和其他详细信息。

       您也可以使用Flex  compiler API 建立项目文件和库文件。库文件的格式为SWC，它里面定义了在应用程序中使用的一系列组件、主题文件或RSL（Runtime Shared Libraries）资源。项目内集合了Flex应用程序和Flex库。这加强了Flex应用程序及其周边资源（assets）间在编译的过程中的依赖性。

Flex complier API的基本要求

        Flex compiler API需要具备如下条件：

•         许可证：您必须拥有Flex Data Service 2的License才能拥有使用包括Flex complier API在内的Flex OEM Kit中任何一部分的权力。
•         JDK：Flex compiler API需要1.4.2及以上版本的JAVA解释器和javac编译器
•         Flex： Flex compiler API 不是一个独立的单机项目. 它需要Flex SDK 或者包含有Flex Data Service 的SDK。当然你也可以使用Flex Builder.。

    Flex Complier API内都包含了什么  

        Flex compiler API 是一个ZIP文件，里面包含了下面的资源：

• flex-compiler-oem.jar：  Flex complier API中的flex2.tools.oem.* API。这个 JAR 文件是在ZIP文件中的 /lib 文件夹下. 当您展开ZIP文件, 您应该把这个文件放入您的 /lib 文件夹下。
• JavaDocs：flex2.tools.oem.* 包中的公有类和接口的 API 文档。这些文件在ZIP文件中的/api文件夹下。
• README.txt： 帮助文件是在ZIP文件的最顶层。它包括安装说明和使用Flex complier API临时许可证的信息。此外，您可以另行下载下面的文件：
• CompilerAPIUserGuide.pdf：Flex 2 Compiler API User Guide 是一个PDF文件，它提供了API的使用文档这个文件在ZIP文件的最顶层。

快速开始

下面的例子描述了如何去创建一个简单的JAVA应用程序去编译Flex应用：

用Flex compiler API创建并编译一个新的应用程序：

 1. 建立一个JAVA文件；例如MyAppCompiler.java：

// java/MyAppCompiler.java

import flex2.tools.oem.Application;

import java.io.*;

public class MyAppCompiler {

    public static void main(String[] args) {

        try {

            Application application = new Application(new 

                File("../apps/TestApp.mxml"));

            application.setOutput(new 

                File("../apps/TestApp.swf"));

            long result = application.build(true);              

            if (result > 0) {

                System.out.println("COMPILE OK");            

            } else {

                System.out.println("COMPILE FAILED");

            }

        } catch (Exception ex) {

            ex.printStackTrace();

        }

    }

}

1、在这个文件里，确保如下几点：

a. 建立一个Application对象。 b. 为Application对象设置一个输出文件。 c. 调用Application.build() 方法。 d. 检查build()方法的返回是是否大于0。

2、用您的JAVA编译器编译这个类；例如： C:\myapps>javac -classpath c:\home\dev\depot\flex\sdk\lib\flex-compiler-oem.jar MyAppCompiler.java 确保flex-compiler-oem.jar 已经加入到您的 Java classpath中。

3. 创建一个MXML 文件；例如TestApp.mxml：

<?xml version="1.0"?>

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

<mx:Label text="Hello World"/>

</mx:Application>

4、用Java解释器运行一个新的Flex应用程序编译器，例如：
C:\myapps>java -classpath c:\home\dev\depot\flex\sdk\lib\flex-compiler-
oem.jar;. MyAppCompiler

确保flex-compiler-oem.jar和当前文件夹加入到您的Java classpath中。

下面的例子使用Configuration类的方法设置了一些配置选项：

// java/MyConfiguringCompiler.java
import flex2.tools.oem.Application;
import flex2.tools.oem.Configuration;
import java.io.*;
public class MyConfiguringCompiler {
    public static void main(String[] args) {
        String outputRoot = "../apps/";
        try {
            Application application = new Application(new 
                File(outputRoot, "ErrorTestApp.mxml"));
            application.setOutput(new 
                File(outputRoot, "ErrorTestApp.swf"));
                
            Configuration config = application.getDefaultConfiguration();
            // Enable ActionScript optimizer.
            config.optimize(true);
            // Disable warnings.            
            config.showActionScriptWarnings(false);
            config.showBindingWarnings(false);
            config.showDeprecationWarnings(false);
            config.showUnusedTypeSelectorWarnings(false);
            // Apply the new configuration to the Application.
            application.setConfiguration(config);
            long result = application.build(true);   
            if (result > 0) {
                System.out.println("COMPILE OK");            
            } else {
                System.out.println("COMPILE FAILED");
            }
        } catch (Exception ex) {
            ex.printStackTrace();
        }
    }
}

配置编译器

        使用Flex complier API时您可以把编译选项传给编译器。您可以用Application或者Library类的getDefaultConfiguration() 方法来得到一个Configuration类的实例，然后在这个实例上设置选项，然后用setConfiguration() 方法设回到Application或Library中。

        如果要设置更多的选项，在the flex2.tools.oem.Configuration API 方法和配置选项之间的关系是1：1映射的。

例如，设置keep-generated-actionscript 编译选项为true，您可以为Configuration类的keepCompilerGeneratedActionScript()方法设置true值：

config.keepCompilerGeneratedActionScript(true);

        一些编译选项像source-path 和 library-path可以用+= 操作符去追加source path 和library path实体。使用这些编译选项时您可以用setSourcePath() 和setLibraryPath() 方法替换掉整个路径。或者，您可以使用addSourcePath() 和 addLibraryPath() 方法给这些path列表里添加path实体。

        有的情况下，Configuration 类可能没有方法对应编译选项。您就需要调用其他的类方法或者调用多个方法。比如，在warnings编译选项中并没有方法允许或者禁止所有的警告，您可以用showActionScriptWarnings(), showBindingWarnings(), showDeprecationWarnings(), 和showUnusedTypeSelectorWarnings() 方法代替。下面的表格列出了这些可选的编译选项的设置方法：

编译选项	等价的complier API或方法
dump-config	调用Configuration.keepConfigurationReport(true) 方法然后调用Report.writeConfigurationReport()方法
include-classes	调用Library.addComponent(java.lang.String)方法
include-file	调用Library.addArchiveFile()方法
include-namespaces	调用Library.addComponent(java.net.URI) 方法
include-sources	调用Library.addComponent(VirtualLocalFile) 或者Library.addComponent(java.io.File) 方法
library-path	调用Configuration.setLibraryPath() 方法替换source path的默认值。调用Configuration.addLibraryPath() 方法为默认的source path追加新值。
link-report	调用Configuration.keepLinkReport(true) 方法，然后调用 Report.writeLinkReport()方法。
output	调用 Application.setOutput() 和 Library.setOutput()/setDirectory()方法
resource-bundle-list	调用 Report.getResourceBundleNames() 方法.
source-path	调用 Configuration.setSourcePath()方法替换source path的默认值。调用Configuration.addSourcePath() 方法为默认的source path追加新值。
version	调用 Report.getCompilerVersion() 方法
warnings	调用showActionScriptWarnings(), showBindingWarnings(), showDeprecationWarnings(), 和showUnusedTypeSelectorWarnings() 方法

关于选项和属性的优先级

       像mxmlc 和 compc这些命令， 默认的Flex compiler API配置使用config.xml文件。为了编译应用程序，编译器也会使用本地配置文件。于是Flex compiler API在flex2.tools.oem.Configuration 应用配置选项来创建最终的编译配置选项组。默认情况下，在flex-config.xml 文件里，编译器被Flex compiler API用编译选项组装默认的配置对象调用。这个文件的位置相对于mxmlc.jar文件的位置。大多情况下，这个文件是在框架目录下, 跟 JAR 文件的lib路径处于同级目录下。编译器也会使用本地配置文件(例如app_name-config.xml)，或者您可以使用addConfiguration() 指向其他位置的配置文件。您使用Flex compiler API 配置的配置选项作为命令行编译选项，拥有相同的优先级。这意味着它们比所有其他形式的选项(flex-config.xml,可选的配置文件, 本地配置文件)的优先级都要高。想查看更多关于使用配置文件的信息请查阅《Building and Deploying Flex 2 Applications》 第二章 “Using the Flex Compilers”。

清除配置

        您可以使用Application.setConguration(null) 方法清除配置。

为应用程序加入资源（assets）

        您可以使用Configuration类中的方法为应用程序加入资源（assets），例如，addExterns(), addIncludes(), 和setTheme()。使用这些方法，您可以加入外部的主题（external themes），类库, 类, RSLs, 其他类型的资源。

       下面的例子使用Configuration类中的setTheme() 方法为现有应用程序加入主题：

// java/MyThemeCompiler.java

import flex2.tools.oem.Application;

import flex2.tools.oem.Configuration;

import java.io.*;

public class MyThemeCompiler {

    public static void main(String[] args) {

        String assetRoot = "../assets/";

        String outputRoot = "../apps/";

        try {

            File[] themeFile = new File[] 

                {new File(assetRoot, "myTheme.css")};

            Application application = 

                new Application(new File(outputRoot, 

                "TestAppWithAssets.mxml"));

            application.setOutput(new File(outputRoot,

                "TestAppWithAssets.swf"));

            Configuration config = application.getDefaultConfiguration();

            config.setTheme(themeFile);            

            application.setConfiguration(config);

            long result = application.build(true);   

            if (result > 0) {

                System.out.println("COMPILE OK");            

            } else {

                System.out.println("COMPILE FAILED");

            }

        } catch (Exception ex) {

            ex.printStackTrace();

        }

    }

}

        在下面的例子中，使用了addLibraryPath()方法加入包含组件的SWC文件，资源（assets）目录 包含了MyComponents.swc 文件：

// java/MyLibraryPathCompiler.java

import flex2.tools.oem.Application;

import flex2.tools.oem.Configuration;

import java.io.*;

public class MyLibraryPathCompiler {

    public static void main(String[] args) {

        String assetRoot = "../assets/";

        String outputRoot = "../apps/";

        try {

            Application application = new Application(new 

                File(outputRoot, "TestAppWithAllAssets.mxml"));

            application.setOutput(new 

                File(outputRoot, "TestAppWithAllAssets.swf"));

            Configuration config = application.getDefaultConfiguration();

            File[] libFile = new File[] 

                {new File(assetRoot, "MyComponents.swc")};

            config.addLibraryPath(libFile);

            application.setConfiguration(config);

            long result = application.build(true);   

            if (result > 0) {

                System.out.println("COMPILE OK");            

            } else {

                System.out.println("COMPILE FAILED");

            }

        } catch (Exception ex) {

            ex.printStackTrace();

        }

    }

}

    在下面的例子中，使用了addSourcePath() 方法加入包含MXML或不在SWC中的ActionScript组件文件的目录。资源（assets）文件夹中包含了一些在TestSourcePathApp 应用程序中使用的MXML文件：

// java/MySourcePathAppCompiler.java
import flex2.tools.oem.Application;
import flex2.tools.oem.Configuration;
import java.io.*;
public class MySourcePathAppCompiler {
    public static void main(String[] args) {
        String assetRoot = "../assets/";
        String outputRoot = "../apps/";
        try {
            File[] sourcePath = new File[] {new File(assetRoot)};
            Application application = new Application(new 
                File(outputRoot, "TestSourcePathApp.mxml"));
            application.setOutput(new 
                File(outputRoot, "TestSourcePathApp.swf"));
            
            Configuration config = application.getDefaultConfiguration();
            // The source path can be a directory. 
            // All MXML and AS files in that directory are added 
            // to the source path.
            config.addSourcePath(sourcePath);
            application.setConfiguration(config);
            long result = application.build(true);   
            if (result > 0) {
                System.out.println("COMPILE OK");            
            } else {
                System.out.println("COMPILE FAILED");
            }
        } catch (Exception ex) {
            ex.printStackTrace();
        }
    }
}

    到此，您也可以使用Flex complier API创建库或组件了。