I need to define a custom namespace in AS3 a couple times a year at most, and nearly every time, I forget how to do it. The docs tell you to use the “namespace” keyword (which I remember), but not where or how to use it (which is what I forget), and google isn’t much help. I always wind up opening mx_internal.as in the Flex SDK as a reference.
With that in mind, here’s a complete guide to using namespaces in AS3. Note that it is about access namespaces, not XML namespaces. Hopefully it saves other devs a few minutes of searching.
What are custom namespaces?
Namespaces allow you to control the access to the members (properties and methods) of a class. You are probably familiar with native access modifiers like public, protected, internal, and private. Custom namespaces allow you to define your own access rules.
What can I use namespaces for?
While there are a range of uses for custom namespaces, three stand out to me as most common:
1. Documenting special conditions for member access. For example, in an evolving API, you may be required to expose methods that aren’t stable. You could place them in a custom namespace (ex. “transitional”), and document it to warn developers that these methods are subject to change. It’s sort of like a EULA for APIs.
2. Providing custom access domains. Namespaces cannot enforce custom access rules (only extend the native access modifiers), but they can provide a way to segregate an API for different user types. For example, you could provide a public API for a library for most users, and an extended API for plugin developers that uses a custom namespace (ex. “plugin”).
As another example of both #1 & 2, Adobe uses the mx_internal namespace to expose methods that need to be accessed widely within the Flex framework, but aren’t meant to be utilized publicly. They document that this namespace is unsupported and subject to change. It has the side benefit of providing hooks for advanced developers that require deep access to the framework and are willing to risk future compatibility problems.
3. Preventing name collisions. You can define members that have the same names in different namespaces. This is particularly handy for dynamic objects. ActionScript 3 uses this for the Proxy object, isolating it’s built in methods in the flash_proxy namespace, so that they are accessible externally, but don’t collide with any user defined methods.
Defining namespaces.
Defining namespaces is easy, just use the “namespace” keyword.
public namespace my_namespace_name; public namespace my_other_namespace = "uri"; |
You can create your namespace within any existing namespace, including the built in namespaces (public, private, et al), but you will usually just make it public.
The name can be whatever you want (except reserved words). The naming convention for namespaces is all-lowercase, with words separated by underscores.
The uri is optional, but helps prevent naming conflicts in the case that someone else uses the same namespace name. This should point to a relevant uri, which ideally hosts some brief information on the namespace (though this is unnecessary). For example, Adobe points to http://www.adobe.com/2006/flex/mx/internal for mx_internal, but doesn’t actually host any content there.
Where do you define namespaces?
You can define namespaces in two places – within a class, or in a separate file. I haven’t been able to come up with a real use case for the former, so we’ll focus on the latter. Simply create a new file with the same name as your namespace inside the appropriate package path, and define the namespace in a package declaration:
// in com/gskinner/utils/my_namespace.as package com.gskinner.utils { public namespace my_namespace = "http://gskinner.com/as/namespaces/utils/my_namespace"; } |
Using namespaces.
First, you need to import your namespace.
import com.gskinner.utils.my_namespace; |
You can now use your namespace in the same way as the built-in namespaces. So instead of specifying a var or function as public or protected, you use your namespace.
my_namespace var myProperty:Number=-1; |
To access class members within a namespace, you import the namespace, and then you use the whacky double-colon namespace syntax to access properties inside it.
import com.gskinner.utils.my_namespace; trace(myDemo.my_namespace::myProperty); // traces -1. |
You can also “use” a namespace, which opens it within the current scope (class or method), and provides access without the namespace qualifier. This approach requires less typing when accessing a number of members in a namespace, but it makes the code more ambiguous (are you accessing a public method, or one in the open namespace?).
import com.gskinner.utils.my_namespace; use namespace my_namespace; trace(myDemo.myProperty); // traces -1. |
Got anything to add? Let me know in the comments.
