Packages

Packages in ActionScript 3.0 are implemented with namespaces, but are not synonymous with them. When you declare a package, you are implicitly creating a special type of namespace that is guaranteed to be known at compile time. Namespaces, when created explicitly, are not necessarily known at compile time.
The following example uses the package directive to create a simple package containing one class.

package samples {
   public class SampleCode {
     public var sampleGreeting:String;
     public function sampleFunction () {
         trace (sampleGreeting + " from sampleFunction()");
            }
       }
}     

The name of the class in this example is SampleCode. Because the class is inside the samples package, the compiler automatically qualifies the class name at compile time into its fully qualified name: samples. SampleCode. The compiler also qualifies the names of any properties or methods, so that sampleGreeting and sampleFunction() become samples.SampleCode.sampleGreeting and samples.SampleCode.sampleFunction(), respectively.

Many users, especially those with Java programming backgrounds, may choose to place only classes at the top-level of a package. ActionScript 3.0, however, supports not only classes at the top-level of a package, but also variables, functions and even statements. One advanced use of this feature is to define a namespace at the top-level of a package so that it will be available to all classes in that package. Note, however, that only two access specifiers, public and internal, are allowed at the top-level of a package. This means that unlike Java, ActionScript 3.0 does not allow you to declare private classes.

In many other ways, however, ActionScript 3.0 packages are similar to packages in the Java programming language. As you can see in the previous example, fully qualified package references are expressed using the dot operator (“.”), just as they are in Java. You can use packages to organize your code into an intuitive hierarchical structure for use by other programmers. This facilitates code sharing by allowing you to create your own package to share with others, and to use packages created by others in your code.

The use of packages also helps to ensure that the identifier names you use are unique and do not conflict with other identifier names. In fact, some would argue that this is the primary benefit of packages. For example, two programmers who wish to share their code with each other may have each created a class called SampleCode. Without packages, this would create a name conflict, and the only resolution would be to rename one of the classes. With packages, however, the name conflict is easily avoided by placing one, or preferably both, of the classes in packages with unique names.

You can also include embedded dots (“.”) in your package name. This allows you to create a hierarchical organization of packages. A good example of this is the flash.xml package provided by the Flash Player API. The flash.xml package contains the legacy XML parser that was used in previous versions of ActionScript. One reason it now resides in the flash.xml package is that the name of the legacy XML class conflicts with the name of the new XML class that implements the XML for ECMAScript (E4X) functionality available in ActionScript 3.0.

Although moving the legacy XML class into a package is a good first step, most users of the legacy XML classes will import the flash.xml package, which will generate the same name conflict unless users remember to always use the fully qualified name of the legacy XML class (flash.xml.XML). To avoid this situation, the legacy XML class is now named XMLDocument.

package flash.xml {
   class XMLDocument {}
   class XMLNode {}
   class XMLSocket {}
}

Most of the Flash Player API is organized under the flash package. For example, flash.display contains the display list API and flash.events contains the new event model. A detailed discussion of the Flash Player API packages can be found in Part III of this book. For more information, see “Flash Player APIs” .

Packages are useful for organizing your code and for preventing name conflicts. You should not confuse the concept of packages with the concept of class inheritance, as they are unrelated. Two classes that reside in the same package will have a namespace in common, but are not necessarily related to each other in any other way. Likewise, a nested package may have no semantic relationship to its parent package.