1. _sidebar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2
2. Home . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.1 Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2 User Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.2.1 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.2.2 IoC Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2.3 Dependency Injection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.2.4 Bean Life Cycle Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.2.5 Event Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.2.6 Service Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.2.7 Client Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.2.8 Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.3 FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.4 Advanced Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.4.1 AutowiredTestCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.4.2 Chaining API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.4.3 Custom Metadata Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.4.4 Module Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.5 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.6 Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.6.1 Presentation Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.7 Migration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.7.1 Updating a Swiz 0.6.4 application to Swiz 1.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.8 Presentations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.9 How To Contribute to Swiz . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.10 Release Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.11 External Community Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
_sidebar

Note About Comments

Feel free to give feedback on the documentation with a comment. But for technical questions, please use the Swiz mailing list.

Save as HTML or PDF

You can export this entire Wiki in HTML or PDF format.

Home
What is Swiz?
Swiz is a framework for Adobe Flex, AIR, and Flash that aims to bring complete simplicity to RIA development. Swiz provides:

Inversion of Control / Dependency Injection

Event handing and mediation
A simple life cycle for asynchronous remote methods
A framework that is decoupled from your application code
Compatibility with both Flex and non-Flex AS3 projects

In contrast to other major frameworks for Flex, Swiz:

Imposes no JEE patterns on your code

No repetitive folder layouts
No boilerplate code on your development
Does not require you to extend framework-specific classes

Swiz represents best practices learned from the top RIA developers at some of the best consulting firms in the industry, enabling Swiz to be
simple, lightweight, and extremely productive.

How Do I Get It?

The latest released version is 1.0. A zip file containing the SWC, source and ASDocs is here: Swiz 1.0 Download and release notes can be
found here: Swiz Release Notes

The latest code can always be found on GitHub at http://github.com/swiz/swiz-framework/.

Visualizing Swiz
Sometimes pictures can help solidify an idea better than words can. With that in mind, here are basic representations of two core Swiz features:
Dependency Injection and Event Mediation.

Dependency Injection Event Mediation

A Little Help Here?
If you have any questions please join the mailing list. You can also find Swiz on Twitter and Swiz on Facebook.

Swiz is provided under the Apache License 2.0

Quick Start

Page Contents:
A Lightning Look at Configuration
The "Big Three": Dependency Injection, Event Handling, and Server Interaction
Adding Dependency Injection
Dispatching and Handling Events
Talking to the Server
There's More Where That Came From

You can download this Quick Start as a Flash Builder FXP or Zip file.

A Lightning Look at Configuration

Configuring Swiz in your Flex or AIR application is very straightforward: declare Swiz, define the beanProviders and config properties, and
optionally define one or more loggingTargets to view debugging messages. Here is an example:

Non-visual components that you want Swiz to manage are defined in a BeanProvider tag. Any beans that you define within the BeanProvider
are processed by Swiz for dependency injection and the creation of event handlers. In the following example, a UserService and a
UserController are created:

The "Big Three": Dependency Injection, Event Handling, and Server Interaction

The three most commonly used features of Swiz are its dependency injection capabilities, its event handling features, and its server interaction
utilities. Let's look at how each of these work.

Adding Dependency Injection

Dependencies are injected by using [Inject] metadata. In this example, the UserService is injected into the UserController:

In addition to injecting a bean, you can inject individual bean properties. In this example, the currentUser property of the UserController is
injected into a UserForm visual component. Note that it is not necessary for the UserForm to be declared as a bean in the BeanProviders tag.
When visual components are added to the display list, Swiz automatically inspects them and processes any metadata tags that are found.

Dispatching and Handling Events

When using Swiz, you dispatch standard Flex events. In this example, we've expanded the UserForm to create and dispatch an event when the
form button is clicked. Swiz listens for events being dispatched within the display list and handles them automatically.

A look at the UserEvent confirms that this is just a simple, standard event. The only thing to note here is that the event has bubbles set to
true. This allows the event to bubble up the display list so that it can be handled by Swiz:

We've seen how to dispatch events from the display list, but how do we handle the events? Swiz provides a [EventHandler] metadata tag to
do this. In the example below, we have expanded the UserController to add an event handler method. In this case, when Swiz encounters an
event of type UserEvent.SAVE_USER_REQUESTED, it will automatically invoke the saveUser method in the UserController. By specifying a
value of "user" for the properties attribute, Swiz will locate the user property in the UserEvent and pass this as a parameter to the handler
method:

One last feature to note regarding event dispatching. We've seen how an event dispatched from the display list will bubble up until it is processed
by Swiz. But what about dispatching events from non-visual components like controllers and services? Swiz offers the [Dispatcher] metadata
tag to meet this need. In the UserService shown below, Swiz will automatically inject an event dispatcher into the dispatcher property. Any
events dispatched though this dispatcher will also be processed by Swiz and trigger any event handler methods associated with the event:

Talking to the Server

Our UserController can now respond when a save user event is dispatched. The final piece of the puzzle is having the application make a call
to the server to actually save the user in a database. Typically, Flex requries you to manually create Responder objects to attach to
AsyncTokens that will handle ResultEvent and FaultEvent. Swiz offers some helpful features to sidestep these manual processes. Below,
you see the final version of our UserController. Because it has the Swiz helper object ServiceHelper injected, we can use its
executeServiceCall() method. This method will automatically obtain the AsyncToken for the RPC call and create Responder objects. In
this case, we call userService.saveUser(), and specify handleSaveUserResult to handle the successful response from the server.
Although it is not shown here, we can also specify a method to use as the fault handler.

There's More Where That Came From

This quick tour has shown how easy it is to configure Swiz and use its core features. But Swiz offers much more than this! Please read the User
Guide, Best Practices, and Advanced Topics to learn more.

User Guide

Welcome to the Swiz User Guide!

Please select a subsection from the menu to view more details about how Swiz works.

Configuration

Page Contents:

Configuration Overview
Logging
setUpEventType, setUpEventPhase and setUpEventPriority
tearDownEventType, tearDownEventPhase and tearDownEventPriority
Default Dispatcher

Configuration Overview

You configure each Swiz instance using the SwizConfig class. It allows you to modify common settings, and to provide values that allow your tags
and code elsewhere to be more concise. Below is an example with all properties shown. Where applicable, they have been set to their default
values. However, in most cases, the default values should work fine (see the note below on Configuration Defaults).

Configuration Defaults
Unless you are specifying your own set up and tear down values, the only configuration values that commonly need to be set
are eventPackages and viewPackages. If you are using Swiz's support for server communication, you may also set
defaultFaultHandler.
 Specifying Packages
Note that due to limitations in the AS3 reflection API, when you define eventPackages, you must specify each package
individually. Children of your specified packages cannot be resolved and must be explicitly set. This limitation does not apply to
viewPackages because they are handled differently, but for consistency it may be useful to use the same rules to define both
sets of packages.

Logging

As you can see above, Swiz includes a basic logging target called SwizTraceTarget to trace debugging information to the console. Due to the
way the MXMLC compiler works, it was not possible to use the built-in Flex logging target(s), because it increases the size of the Swiz swc by an
unacceptable amount. If necessary, you can extend the AbstractSwizLoggingTarget to customize the output.

setUpEventType, setUpEventPhase and setUpEventPriority

These properties configure the listener that Swiz will use to trigger the set up of views (assuming they are eligible) to inject dependencies, create
event handlers, etc. The default is a capture phase listener (to catch all views regardless of their place in the display list hierarchy) for the
Event.ADDED_TO_STAGE event, with a priority of 50.

tearDownEventType, tearDownEventPhase and tearDownEventPriority

These properties configure the listener that Swiz will use to trigger the tearing down of views to clean up injected dependencies, remove event
handlers, etc. The default is a capture phase listener for the Event.REMOVED_FROM_STAGE event, with a priority of 50.

Default Dispatcher

The default dispatcher value is "global". This means that in the case where a Swiz instance is the child of another Swiz instance, the child will use
the parent dispatcher. This allows for easy communication between Swiz instances, since they all share the same event dispatcher. However, if
you want to force a child Swiz to use it's own dispatcher, you can set this value to "local". In most cases, developers should not need to change
the default value ("global"). More information on parent-child Swiz instances can be found in the section on Module support.

IoC Container

Page Contents:

The BeanProvider Class

Prototype Beans

The BeanProvider Class

The IoC (Inversion of control) container of Swiz is the BeanProvider class. In the BeanProvider you typically define non-view classes that you
want registered with the framework and available as injection sources or targets. This generally means models, controllers, delegates and
services. Beans are defined using regular MXML tags:

Most applications define at least one Beans.mxml in the root package and pass it to the Swiz tag's beanProviders property in the application’s
main MXML file. For clarity and simplicity, it is recommended that you define your beans in a separate file, using BeanProvider as the root tag, as
shown above. However, if for some reason you choose to define your beans inline in the Swiz tag, you'll need to wrap your objects with the Bean
tag to ensure they are processed correctly:

Prototype Beans

Similar to Spring’s prototype scope, Swiz provides a Prototype tag. Prototype enables a few different things:

Constructor injection – you can pass up to 8 arguments to your bean’s constructor

Unique copy for each injection target (like prototype scope behavior in Spring)
Deferred instantiation – Prototype beans will not be created until they are needed for injection

If you want deferred instantiation and/or constructor injection but not a unique copy for each injection you can set Prototype’s
singleton property to true.
Dependency Injection

Page Contents:

Dependency Injection Overview

Inject by type
Inject by name
Inject bean property
Two way bindings
Setter injection
Injection destination

Dependency Injection Overview

The IoC Container of Swiz is the BeanProvider class. Any beans defined in a registered BeanProvider can be injected into other registered beans
or into views added to the display list.

Defining an injection target is done using the [Inject] metadata tag. Common injection scenarios include the following:

Inject Model into View

Inject Model into Controller
Inject Delegate into Controller
Inject Service into Delegate

Due to restrictions imposed by the AVM, Swiz cannot inject into private, protected or internal members.

By default, injections in view components happen during the ADDED_TO_STAGE event. This behavior can be modified by
changing the Swiz configuration. It is important to understand that this means that injections occur after the
CREATION_COMPLETE event. If you need to trigger logic during creation that depends on injections, use a [PostConstruct]
method.

Inject by type

If you define exactly one bean of a given type you can inject it into a matching destination with a plain [Inject] tag. Note this also supports injecting
a concrete implementation of an interface to which the destination is typed. In other words, if a property decorated with [Inject] is of type
IUserService, Swiz will correctly inject a bean implementing that interface, such as UserService or MockUserService.

Best Practice
You should inject by type whenever possible. It avoids reliance on string based names, which can lead to run time errors
caused by misspellings.

Automatic Creation and Injection of Built-In Helper Classes

If Swiz encounters an [Inject] tag for a property typed to ServiceHelper, IServiceHelper, URLRequestHelper,
IURLRequestHelper, or MockDelegateHelper, and there is no matching Bean defined in a BeanProvider, Swiz will
automatically create a bean of the correct type and inject it for you.

Inject by name

If you have more than one bean of a given type defined you can request that a bean with a specific name be injected. This bean name must
match the id attribute of the bean's tag as defined in your BeanProvider.

Quick Tip
"source" is the default attribute of [Inject], so the above tag could also be written as [Inject( "userService" )]
Inject bean property

Swiz can also inject public bean properties, rather than just the beans themselves using dot notation. In the following example "userModel" is the
name of a bean, and we are injecting its currentUser property.

Quick Tip
If the bean property is bindable and the decorated property is public, you can have Swiz create a binding to the source property
by adding bind="true" to the [Inject] tag.

Two way bindings

To set up a reverse binding, so the bean property will receive updates made to the injection target, you can set the twoWay attribute of the [Inject]
tag to true. This of course requires that the injection target is bindable as well.

Setter injection

Swiz can also inject values into single argument methods. All of the attributes and policies mentioned above apply to setter injection as well, with
the exception of twoWay.

Injection destination

Sometimes it's useful to define an injection someplace other than directly on a property/method. This is especially true in MXML views, where
decorating a child component's property is not possible. Rather than creating a local variable and binding your component property to it, you can
simply use the destination attribute of [Inject]. If this were defined in an MXML file, it would be wrapped in a Metadata tag.

Take care to ensure that the injection destination will be created and available by the time your injections are processed. The
injection processing trigger can be configured in SwizConfig, but defaults to the ADDED_TO_STAGE event.

Bean Life Cycle Management

Page Contents:

Manually Creating and Destroying Beans

[PostConstruct] and [PreDestroy]
SwizConfig Options
Swiz and Flex Life Cycle Steps

Manually Creating and Destroying Beans

Swiz provides an event-based mechanism to create or destroy beans. To create a new bean, you can dispatch the BeanEvent.SET_UP_BEAN
or BeanEvent.ADD_BEAN events:

Both SET_UP_BEAN and ADD_BEAN will process the target object as a bean. The difference between these events is that ADD_BEAN will also
add the bean as a singleton to the BeanFactory cache, while SET_UP_BEAN does not add the new bean to the cache.

Similarly, to destroy a bean, you dispach the BeanEvent.TEAR_DOWN_BEAN or BeanEvent.REMOVE_BEAN events:

The tear down events mirror the set up events discussed previously: TEAR_DOWN_BEAN cleans up the target by removing injections, event
handlers, etc., while REMOVE_BEAN cleans up the bean as well as removing it from the singleton cache in the BeanFactory.

Since BeanEvent is a bubbling event, you can dispatch it from a view. If you dispatch them from non-view beans, be sure you
use an injected dispatcher so that Swiz can handle the event.
If necessary, you can directly call the setUpBean() and tearDownBean() methods on the BeanFactory. Since these methods both take a
Bean instance as an argument, you can use the createBeanForSource() method on the BeanFactory to generate a Bean instance that you
can then pass into the set up and tear down methods. However, in general the event-based approach to creating and tearing down beans should
be the preferred approach.

[PostConstruct] and [PreDestroy]

Swiz provides two metadata tags which allow you to trigger methods when any bean is set up or torn down. You can decorate a public method
with [PostConstruct] and that method will be invoked by the framework after the bean has been set up, had dependencies injected, and had
mediators created. For example:

Similarly, a public method decorated with [PreDestroy] will be called when a bean is destroyed by Swiz. This would happen if a UI component
is garbage collected, or a module is unloaded.

SwizConfig Options

Six configuration options are available in the SwizConfig object to specify how UI components are handled by the framework. These are
setUpEventType, setUpEventPhase, setUpEventPriority, and the corresponding tearDownEventType, tearDownEventPhase, and
tearDownEventPriority. Normally, you can leave these at their default values. But if you need to, you can modify these to alter how Swiz
creates and destroys beans that are UI components.

The default setUpEventType is "addedToStage". This means that whenever a UI component is added to the stage, Swiz will inspect the
component and process any metadata it finds. Any dependency injections and event mediators will happen at this time. As mentioned, you may
change this value if "addedToStage" is not ideal for your situation. "creationComplete" is another commonly used setUpEventType.

Be careful if you use an event type that occurs early in the Flex component life cycle, such as "preinitialize", since child
components have not been created yet. Conversely, be aware that the Flex framework may internally trigger the removal and
addition of components at unexpected times, such as when scroll bars are added to a resized container. In the unlikely (but
possible) event that this causes problems, consider an alternative setUpEventType.

At the other end of the bean life cycle, the default tearDownEventType is "removedFromStage". This means that when a UI component is
removed from the stage, Swiz will perform clean up activities such as removing event mediators.

If you require even more fine-grained control, you can specify alternative values for the phase and priority used for the set up and tear down of
beans. Typically, these won't need to be changed, but the options are there in case they are needed.

You can also use the ISetUpValidator and ITearDownValidator interfaces with UI components to control whether set up
or tear down are allowed.

Swiz and Flex Life Cycle Steps

The following table shows the steps that Flex and Swiz will go through on application startup:

Type Step

Flex Preinitialize event

Swiz dispatcher set

Swiz Swiz created event

Swiz domain set

Swiz Global dispatcher set

Swiz Processors initialized

Swiz Bean factory initialized

Swiz setUpEvent and tearDownEvent values set from SwizConfig

 Swiz Beans defined in the BeanProvider(s) are processed

Swiz (per bean) beanFactory.setUpBean()

Swiz (per bean) [Inject] processed

Swiz (per bean) [EventHandler] processed

Swiz (per bean) [Dispatcher] processed

Swiz (per bean) Default custom metadata processed

Swiz (per bean) [PostConstruct] processed

Flex Initialize event

Flex Creation complete event

Flex Added to stage event

Flex Display objects in the display list are processed (see table below)

Flex Application complete event

Flex Update complete event

The following table shows the steps that Flex and Swiz will go through when a new display object is set up:

Type Step

Flex Invalidation

Flex Property bindings

Flex Preinitialize

Flex Create children

Flex Initialize event

Flex Commit properties

Flex Resize

Flex Render

Flex Measure

Flex Set actual size

Flex Update display list

Flex Creation complete event

Flex Added event

Flex Added to stage event

Swiz beanFactory.setUpBean()

Swiz [Inject] processed

Swiz [EventHandler] processed

Swiz [Dispatcher] processed

Swiz Default custom metadata processed

Swiz [PostConstruct] processed

Flex Update complete event

The following table shows the steps that Flex and Swiz will go through when a display object is torn down:

Type Step

Flex Removed event

Flex Removed from stage event

Swiz [PreDestroy] processed

Swiz [Inject] tear down

Swiz [EventHandler] tear down

Swiz [Dispatcher] tear down

Swiz Default custom metadata tear down

Event Handling

Page Contents:

Dispatching Events
Handling Events with [EventHandler]
Event Handling Using Class and Constant Names
Event Handling Using Event Type Value
[EventHandler] tag options
properties attribute
Other attributes
Handling Multiple Events from a Single Method

Swiz offers features to assist with both the dispatching and handling of events within an application. The following sections explain these features
in detail.

Dispatching Events

Application events typically fall into two categories: those dispatched from children of DisplayObject, and those dispatched from non-UI
objects. Swiz makes it easy to handle both kinds of events in a standard way.

Dispatching events from UI components is done using the standard dispatchEvent() method that DisplayObject provides. If you dispatch
events that bubble, Swiz can listen for these events in the root container and invoke event handlers to handle these events.

Dispatching events from non-UI component beans is done using an event dispatcher provided by Swiz. There are two ways to instruct Swiz to
inject a dispatcher. The most common way is to use the [Dispatcher] metadata tag. Swiz will automatically inject the dispatcher into a public
property decorated with this metadata.

The other option is to implement the Swiz IDispatcherAware interface. Since implementing this interface creates a direct dependency on the
Swiz framework, it should be avoided if possible.

Once the dispatcher is injected, you can use it to dispatch events that can be handled using metadata-based event handlers. Event handlers are
described in the next section.

In situations where you have two or more Swiz instances in a parent/child relationship, you can exercise some additional control
over how events are dispatched and handled. See the section on Module Support for more information.

Handling Events with [EventHandler]

Swiz handles application events using the {[EventHandler] metadata tag. [EventHandler] provides several benefits:

You no longer need to manually declare event listeners in your code. Swiz will transparently create an event listener for the specified
event when the bean is created, and will invoke the target method whenever that event is captured. Further, Swiz will automatically
remove the event listener when the bean is destroyed or removed from the display list.
You no longer need event-specific handler methods to respond to events. [EventHandler] methods can be declared without
specifying an Event object as a method argument (see below). As a result, you can easily invoke these methods yourself, outside the
 context of responding to an event, in addition to having Swiz invoke them automatically.
A single method can easily respond to multiple event types.
Because the methods are annotated with metadata, it is possible to introspect a class to determine what events it will respond to. This is
not possible when the code manually creates event listeners.

In order for an event to be handled, it must be dispatched from the Swiz dispatcher (as shown above) or be a bubbling event. [EventHandler]
tags are defined on methods and must specify the event to be handled. The event can be specified using the string value of the event's type
property, or by using the class and constant names of the event.

Event Handling Using Class and Constant Names

This is the recommended approach since Swiz can verify the event class exists and has a constant with the provided name. This syntax assumes
you have added "com.foo.events" to the eventPackages property of SwizConfig.

If you do not specify any eventPackages, you can provide the fully qualified path in the [EventHandler] tag:

Event Handling Using Event Type Value

Good for quick prototyping but lacks error checking and could suffer from collisions. Not recommended.

[EventHandler] tag options

The examples above show methods that take the target event as an argument, but in some cases you don't need the event passed to your
method. Swiz will intelligently examine the signature of your method and call it without parameters if that is how it's defined.

properties attribute

You can also specify a comma delimited list of property names in the tag to have the matching properties pulled off of the event and passed into
your method. This can be useful for allowing methods to be defined in a more semantic manner to mask the fact that they are event listeners.

Other attributes

Since [EventHandler] causes Swiz to create an event listener behind the scenes, it also supports some related attributes. useCapture,
priority, stopPropagation and stopImmediatePropagation are all supported, and Swiz will handle their implementation for you.
useCapture and priority map directly to the useCapture and priority parameters of the resulting listener. Setting stopPropagation
or stopImmediatePropagation to "true" will cause Swiz to automatically call the corresponding methods on the event after your method
executes.

Handling Multiple Events from a Single Method

It is possible to handle multiple events using a single method:

Additionally, you can handle any event type of a given event using a wildcard:

Service Layer
Interacting with remote services is a feature found in almost every RIA created. Because of this, Swiz has made it a priority to streamline and
enhance this aspect of development. There are four primary classes you will interact with in the service layer of your Swiz application.

ServiceHelper

The ServiceHelper class is probably the most common class you will use in the service layer of your Swiz application. ServiceHelper is a class
that simplifies and improves your interactions with service classes that return an AsyncToken. This includes RemoteObject, HTTPService and
WebService. These services will typically be defined as beans and injected into one of your own classes. ServiceHelper's executeServiceCall()
method is a concise way to call a service, define handlers for the call and specify objects to be passed to your result handler.

The following example shows a simple service call as it looks when using ServiceHelper. In this example the ServiceHelper has been defined as a
bean and injected, but you can instantiate your own instance if you prefer. Also notice that you are able to define an array of parameters that will
be passed to the result handler when the service returns. This can be very useful for maintaining context between calls and simplifying your result
handler code. The first parameter of executeServiceCall() is an AsyncToken so we simply perform the RemoteObject method call, which returns
an AsyncToken, inline.
URLRequestHelper

Remote calls that do not return an AsyncToken are generally implemented using the URLRequest and URLLoader classes. Swiz therefore
provides the URLRequestHelper class, whose executeURLRequest() method works much like executeServiceCall(). The slight differences can be
seen below, but can be summed up in that you do not directly create a URLLoader instance or call load() because Swiz handles those aspects for
you, and there are extra (optional) handlers that can be defined.

Client Persistence
Swiz provides two ways to help with client persistence. In both Flex and AIR projects you can use the SharedObjectBean. In AIR projects, you
can also use the EncryptedLocalStorageBean, which can be found in the Swiz Desktop Extensions project on GitHub. (The
EncryptedLocalStorageBean is kept in a separate project to avoid having a framework dependency on the AIR libraries.)

SharedObjectBean

To use the SharedObjectBean, you simply declare it in a BeanProvider:

Inject the instance into your model and declare a bindable getter/setter:

Interfaces
Swiz provides several interfaces to enable manual control over certain features, or as an alternative to using certain metadata tags.

ISetUpValidator

Implementing this interface will instruct Swiz to invoke the allowSetUp() method of the bean before the bean is set up. If this method returns
true, set up will proceed. If it returns false, Swiz will not set up the bean.

ITearDownValidator

Implementing this interface will instruct Swiz to invoke the allowTearDown() method of the bean before the bean is torn down. If this method
returns true, tear down will proceed. If it returns false, Swiz will not tear down the bean.

ISetUpValidator and ITearDownValidator are primarily meant for use in view components, to allow specific views to opt
out of set up or tear down. In these cases, the developer can manually control set up or tear down of the views.

IInitializing

Implementing this interface will instruct Swiz to invoke the afterPropertiesSet() method of the bean after the bean is set up.

IDisposable

Implementing this interface will instruct Swiz to invoke the destroy() method of the bean when the bean is destroyed

IDispatcherAware

Implementing this interface will instruct Swiz to inject an IEventDispatcher into the bean's dispatcher property when it is set up.

Best Practice
In order to minimize coupling to the Swiz framework, using the [PostConstruct], [PreDestroy] and [Dispatcher]
metadata tags should be favored over use of IInitializing, IDisposable and IDispatcherAware.

IBeanFactoryAware

Implementing this interface will instruct Swiz to inject the Swiz IBeanFactory into the bean's beanFactory property when it is set up.

ISwizAware
Implementing this interface will instruct Swiz to inject itself into the bean's swiz property when it is set up.

FAQ
Is there a mailing list where I can get help from the Swiz community?
If I am exporting a release build for a Swiz project, what compiler arguments do I need to retain the custom metadata?
If I am building the Swiz framework from the source code, what compiler arguments do I need?
I try to access my injected property during creationComplete but the reference is still null?
Does Swiz work with Flex 4?
Does Swiz work with Adobe AIR?
I have dispatched an event from a view but the [EventHandler] is not invoked?
Why aren't new PopUp or AIR windows processed by Swiz (especially if created from within a Module)?
Why aren't bubbling events dispatched from a PopUp handled by Swiz?
Where is my application logic starting point?
How should I dispatch events from bean classes?
Why did my view not get injections processed?
I defined a WebService object in my Beans.mxml, but my web service calls don't seem to work. What's wrong?
Why do I get an error when using Swiz in a Flash Builder project when I use Design View?

Is there a mailing list where I can get help from the Swiz community?

Absolutely, you can find the Swiz group at http://groups.google.com/group/swiz-framework.

If I am exporting a release build for a Swiz project, what compiler arguments do I need to retain the custom metadata?

-keep-as3-metadata+=Inject,Autowire,EventHandler,Mediate,Dispatcher,PostConstruct,PreDestroy

If I am building the Swiz framework from the source code, what compiler arguments do I need?

-keep-as3-metadata+=Inject,Autowire,EventHandler,Mediate,Dispatcher,PostConstruct,PreDestroy
-namespace http://swiz.swizframework.org manifest.xml
-include-namespaces http://swiz.swizframework.org

Be sure you only compile the /src directory into the library. Trying to compile the other packages, such as /tests, will result in library compile
errors.

I try to access my injected property during creationComplete but the reference is still null?

Swiz injects dependencies when the view's addedToStage event is dispatched, which is after creationComplete. Inject to a setter function to have
direct access to the injected reference, or move your logic into a method decorated with [PostConstruct].

Does Swiz work with Flex 4?

Yes, Swiz works with Flex 2,3 and 4. The prerelease version of Flex 4.5 is not yet supported, but will be in Swiz 1.1.

Does Swiz work with Adobe AIR?

Yes, there is in general no difference between Web or AIR development. An additional Desktop Extensions library is available to add
desktop-specific features.

I have dispatched an event from a view but the [EventHandler] is not invoked?

Ensure that the bubbles property of the event is true.

Why aren't new PopUp or AIR windows processed by Swiz (especially if created from within a Module)?

Because PopUps and NativeWindows are not part of the standard display list, Swiz has no way to know which Swiz instance is the owner of the
window. To deal with this, you can have the class that creates the window implement ISwizAware. Once you have the correct Swiz instance
injected, you can call the registerWindow() method on that Swiz instance to associate that window with the specified instance of Swiz. The
window can then be processed correctly.
Why aren't bubbling events dispatched from a PopUp handled by Swiz?

Swiz uses the display object where it was created as its "root event dispatcher", and it listens for events on that event dispatcher. However,
PopUps are not added to this display list, they are added as direct children of the SystemManager object, since they must appear above
everything else in the application. As a result, events dispatched from PopUps don't bubble up to the Swiz dispatcher. However, the solution to
this is simple: just use [Dispatcher] to inject the Swiz dispatcher into your PopUp, and dispatch events through it. This way, Swiz can process
them.

Where is my application logic starting point?

Let your main controller implement IInitializingBean, or decorate a method with [PostConstruct], and start with your application logic in that
method. Swiz calls these methods on beans when the injection process is complete.

How should I dispatch events from bean classes?

You should inject a dispatcher using the [Dispatcher] metadata, and dispatch application events through this dispatcher.

Why did my view not get injections processed?

Be sure that the viewPackages in the SwizConfig tag are set correctly.

I defined a WebService object in my Beans.mxml, but my web service calls don't seem to work. What's wrong?

The Flex WebService class actually has two implementations, one for MXML and one for AS3. If you define a WebService within a UIComponent,
the Flex framework automatically triggers a load of the web service's WSDL in the UIComponent's creationComplete() handler. However, the AS3
version does not (it has no creationComplete() handler). Because the BeanProvider is not a UIComponent, this automatic loading of the WSDL is
not done by the Flex framework. As a result, you must call loadWSDL() on your web service before you can use it, because you are actually using
the WebService's AS3 implementation.

Why do I get an error when using Swiz in a Flash Builder project when I use Design View?

Researching this seems to indicate that it can happen with any .swc where the .swc was compiled using a version of the SDK other than the
version used by the project. Since there are so many possible SDK versions, creating separate versions of Swiz for all of them is not possible. If
you need to use Design View, and you're using an SDK other than the one the framework was compiled with, we recommend that you download
the source code, set up the framework as a library project, and add the library project to your application project. This should resolve the Design
View error.

Advanced Topics
This section covers more advanced Swiz topics, such as the Chaining API and custom metadata.

AutowiredTestCase
One of the utility classes that is part of the Swiz library is AutowiredTestCase. As the name implies, you can use this class to help test your
Swiz applications. Let's look at a sample FlexUnit 4 test that uses AutowiredTestCase. First, the class under test:

You can see this is a simple controller, which responds to the CONTROLLER_ACTION_REQUESTED event, updates a property, and then
dispatches CONTROLLER_ACTION_COMPLETE. We want to test that the controller is responding to the correct event, property updating the
property, and finally dispatching the completion event.

The event itself is a simple event class:

Finally, the test case itself:

We start off setting up an instance of Swiz that the test can use. AutowiredTestCase has a method marked with [Before] metadata, so that
FlexUnit runs it before each test. Next, create an instance of the class under test (MyController), then set the event packages on the
SwizConfig. Finally, we place the MyController instance into a BeanProvider, so that Swiz will process it as a bean. This way, any Swiz
metadata in MyController is processed.

The test method dispatches a CONTROLLER_ACTION_REQUESTED event. If all goes well, the event handler in the controller should run, update
the property, and then the controller will dispatch the completion event. Running the test produces a passing result.

Note that because Swiz actually processes your test case itself as a bean, you can use Swiz metadata in your test if you want or need to. So
injecting a dispatcher, handling an event, or testing custom metadata processors are all possible as well.

Chaining API

Page Contents:

Chaining API Overview

Provided implementations
Custom implementations
Automatic Asynchronous Handling in Chains
Go forth and chain stuff!

Chaining API Overview

Swiz provides a simple, yet powerful and extensible API for chaining actions together. At the heart of this API are the IChain and IChainStep
interfaces. Let's look at them here, starting with IChain.

Most of the methods are self explanatory, so we'll only discuss the most important one directly. The doProceed() method is where a chain does its
work. It's where EventChain dispatches events, and where CommandChain executes commands. If you clicked either of those links, you may
have noticed that both chain types contain very little code other than their doProceed() implementations. This is because they both extend
AbstractChain, which implements the entire IChain interface besides doProceed(). It does not actually implement IChain, however, which forces
custom chain types to do so and to implement doProceed(). AbstractChain does implement IChainStep though, which means chains can be
nested. Also note that chains can be run in either sequence or parallel mode, with constants defined for each in the ChainType class.

IChainStep is the base interface for objects that can be part of a chain. The methods are again pretty self explanatory, but do notice the
complete() and error() methods, which correspond to the stepComplete() and stepError() methods of IChain.

The last interface of the Swiz chaining API is IAutonomousChainStep.

While chains will often have specific logic for executing their constituent steps, sometimes it is beneficial for a step to control its own execution.
This is especially useful for constructing chains with steps of varying types.

Provided implementations

Swiz provides some useful implementations of the chaining API for you. We previously mentioned EventChain, which is exactly what it sounds
like. It allows you to string together EventChainStep instances, and also supports IAutonomousChainStep instances. EventChains can be
extremely useful for things like application boot strapping and making multiple remote service calls.

CommandChain provides a mechanism for assembling CommandChainStep instances, as well as AsyncCommandChainStep instances (they
extend CommandChainStep and implement IResponder) and implementations of IAutonomousChainStep.

Here is an example of a simple EventChain that dispatches a series of events as a single unit:

EventChainSteps may optionally specify a dispatcher. If none is specified, the EventChain will assign its dispatcher to the EventChainStep before
executing that step.

FunctionChainStep is another useful class that implements IAutonomousChainStep and allows for deferred function invocation.
Finally, note that BaseChainStep provides a base implementation of IChainStep, making your custom implementations that much easier to write.

Custom implementations

It is extremely easy to extend the chaining API to meet your specific needs. As mentioned above, creating a custom chain type essentially boils
down to extending AbstractChain, adding "implements IChain" and then implementing the doProceed() method. Your doProceed() method could
execute custom chain step types, log or otherwise audit chain progress or perform any other custom behavior you desire. A simple chain that
relies on autonomous steps is shown below.

Custom chain steps can be made to perform virtually any action. They will need to implement IChainStep, which is most easily done by extending
BaseChainStep. If they implement IAutonomousChainStep they can be virtually self contained, and can easily be combined with other chain step
types. An example of a custom chain step which sets a property on an object is shown below.

Automatic Asynchronous Handling in Chains

The Event Chaining API also supports automatic asynchronous handling of chain steps. If an [EventHandler] method is called as part of an
event chain, it can return an AsyncToken or IAsynchronousOperation to participate in automatic asynchronous handling. In that case, the chain
that is executing will wait until the operation is complete before proceeding to the next chain step. Further, if there are multiple [EventHandler]
's for a given Event, the chain will wait until all associated asynchronous operations are complete before proceeding to the next chain step.

Not all asynchronous Flash or Flex API operations return AsyncToken. Consequently, the internal logic related to asynchronous handling is based
upon IAsynchronousOperation. Swiz provides three concrete implementations that adapt typical Flash / Flex asynchronous operations into
IAsynchronousOperations.

1. AsyncTokenOperation - which adapts an AsyncToken.

2. AsynchronousChainOperation - which adapts an asynchronous IChain.
3. AsynchronousIOOperation - which adapts Flash or Flex API operations that signal success or failure by dispatching Event.COMPLETE /
Event.CANCEL / IOEvent.IO_ERROR / SecurityErrorEvent.SECURITY_ERROR events (ex. FileReference). AsynchronousIOOperation
extends AbstractAsynchronousDispatcherOperation, so you can extend this abstract base class to adapt other asynchronous operations
that signal their success or failure via Events if necessary.

As noted earlier, [EventHandler] methods can simply return an AsyncToken. The [EventHandler] metadata processor
will automatically adapt the AsyncToken via AsyncTokenOperation.

For example, here is an example of an event chain that will automatically wait for a service call to complete before moving on to the next step:

As another example, a URL request is adapted via AsynchronousIOOperation to allow Swiz to wait for completion before the chain proceeds:

An [EventHandler] method can also construct an asynchronous chain and return that chain as an operation (adapting it via
AsynchronousChainOperation). In that case, the original EventChainStep will not proceed until the entire child chain is complete.

Go forth and chain stuff!

Hopefully this page has shown you the ease, power and extensibility of the Swiz chaining API. If you have questions or comments about the API
or any of the built in implementations, or even just ideas you'd like to discuss, please head over to the mailing list and we'll be happy to help!

Custom Metadata Processors

Custom metadata processors are one of the most powerful and interesting features Swiz has to offer. This page contains links to custom
processors created by the community, as well as instructions on how to create your own custom metadata processor.
Created by the community

[URLMapping] - Deep linking made crazy easy

[MediateSignal] - Mediate AS3 Signals like you would events
[Resource] - Simplified localization coding
[Logger] - Simplified logging
[Bind] - Binding for the Flight framework via metadata
[MediateView] - Passes view components into beans by type or ID

Creating your own

Coming soon

Module Support

Parent and Child Swiz Instances

Swiz supports the concept of parent and child instances. Typically, this capability is used in conjunction with Modules. When you load a module
that contains a Swiz instance as a child of another Swiz-based application, the framework will create a parent-child relationship between these
two instances of Swiz. This happens automatically, meaning that the developer should not have to do any manual setup or configuration to use
this feature. There is a sample application that demonstrates how Swiz can work with Modules at the Github repository.

Here is a graphical representation of how the module support works and what capabilities it offers:

The one main issue that developers encounter related to module support has to do with Swiz metadata-based event handling. The
[EventHandler] metadata tag only contains a string value representing the event class and constant name. As a result, when Swiz attempts to
validate the event, you will receive an error if that event class was not compiled into the Module. This is because Swiz cannot locate the event
class in the ApplicationDomain. The developer must ensure that event classes defined outside of the module are included in the compiled
module. In practice, this simply means adding a variable declaration somewhere that is typed to that event. As long as an actual reference to the
event type exists somewhere within the module, that class will be compiled into the module. This allows Swiz to locate the class reference and
validate the event constants.

Note that this is not actually a Swiz-specific issue. The compiler only includes classes that are actually referenced in an application; all others are
discarded for optimization purposes.

The Local and Global Scopes

Swiz offers some additional control over how events are dispatched and handled between parent and child Swiz instances. Most developers will
probably never need to concern themselves with this fine-grained control, but it is described here for the cases where it is desired.

The [Dispatcher] and [EventHandler] metadata tags allow for an optional attribute called scope, which can be set to "local" or "global".
The default value for both of these attributes is "global".

If a [Dispatcher] metadata tag specifies scope="local", the dispatcher for that Swiz instance is injected. When scope="global" is
specified, the dispatcher for the top-level Swiz instance is injected.

Similarly, if an [EventHandler] metadata tag specifies scope="local", only events dispatched through the local dispatcher are handled by
the decorated method. When scope="global" is specified, events dispatched through the global dispatcher are handled.

Since this may make more sense when visualized, here is a graphic depicting the local and global scopes:
Examples
The swiz-examples repository on Github contains a number of examples. These include the Quick Start app, examples of Module integration, the
Chaining API, and more. We'll keep adding more over time, too!

Best Practices
This section will contain a collection of Swiz best practices that will be updated on an ongoing basis.

Presentation Model
The presentation model (PM) approach is the recommended view layer architecture for Swiz.
The goal is to remove any logic from the view and let the PM handle the view logic.

The PM has to be declared in the BeanProvider and the recommended way is to declare it as a Prototype so the PM will only be created
(instantiated) when the corresponding view is added to the stage.

Beans.mxml

<?xml version="1.0" encoding="utf-8"?>

<swiz:BeanProvider xmlns:swiz="http://swiz.swizframework.org" xmlns:fx="http://ns.adobe.com/mxml/2009"
>
<fx:Script>
<![CDATA[
import example.model.presentation.MyPresentationModel;
]]>
</fx:Script>
<swiz:Prototype type="{MyPresentationModel}" />

</swiz:BeanProvider>

The view gets the PM injected and binds data from it and delegates all interactions (events) to the PM.
 MyView.mxml

<?xml version="1.0" encoding="utf-8"?>

<s:SkinnableContainer xmlns:fx="http://ns.adobe.com/mxml/2009" xmlns:s=
"library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx" currentState="{model.currentState}">
<fx:Script>
<![CDATA[
import example.model.presentation.MyPresentationModel;
import org.swizframework.events.BeanEvent;

[Bindable]
[Inject]
public var model:MyPresentationModel;

[PreDestroy]
public function cleanUp():void
{
dispatchEvent( new BeanEvent( BeanEvent.TEAR_DOWN_BEAN, model ) );
}

]]>
</fx:Script>

<s:layout>
<s:VerticalLayout />
</s:layout>

<s:states>
<s:State name="default" />
<s:State name="detail" />
</s:states>

<s:List labelField="{model.listLabelField}" dataProvider="{model.dataProvider}" change=

"model.changeListIndex(event.newIndex)" />

<s:Label includeIn="detail" text="{model.selectedItem.title}" />

<s:Button includeIn="detail" label="Edit" click="model.edit()" />

</s:SkinnableContainer>

The PM is a independent unit and only gets data injected from the application layer.
 MyPresentationModel.as

package example.model.presentation
{

import flash.events.IEventDispatcher;

public class MyPresentationModel

{
[Dispatcher]
public var dispatcher:IEventDispatcher;

[Bindable]
public var currentState:String;

[Bindable]
[Inject("appModel.list")]
public var dataProvider:IList;

[Bindable]
public var selectedItem:Object;

public function MyPresentationModel()

{
}

public function changeListIndex(index:int):void

{
if(index != -1){
currentState = "edit";
selectedItem = dataProvider.getItemAt(index);
}else{
currentState = "default";
selectedItem = null;
}
}

public function edit():void

{
dispatcher.dispatchEvent(new MyEvent(MyEvent.EDIT, selectedItem));
}
}
}

Having no logic in the view itself also means that you only have to unit test your PM.

Migration Guide
Tips for migrating from earlier versions

Updating a Swiz 0.6.4 application to Swiz 1.0

Updating a Swiz 0.6.4 application to Swiz 1.0 will require the following changes:

Update configuration and creation of Swiz

Prior to 1.0, there was only one instance of Swiz. 1.0 now allows for multiple versions of Swiz, primarily to support modules and separate AIR
windows. As a result, the creation of Swiz within the application will need to be modified.

In a 0.6.4 application, Swiz was created like this:

In Swiz 1.0, this would look like:

You might also note that several of the properties on Swiz have changed:

the strict property has been renamed validateEventTypes, and now defaults to true so in most cases it can be removed
mediateBubbledEvents has been removed since Swiz 1.0 mediates bubbled events automatically
the beanLoaders property has been renamed to beanProviders, and has been moved to the Swiz class
the eventPackages and viewPackages now accept package paths in both the format myapp.events and myapp.events.*. Note
that you still need to specify child packages separately even if you use the .* syntax.
the injectionEvent property has been renamed setUpEventType, and now defaults to Event.ADDED_TO_STAGE instead of
Event.PREINITIALIZE

Full details on configuration and the default values for 1.0 can be found in the Configuration section.

The BeanLoader class has been deprecated in favor of BeanProvider. BeanLoader will still work in 1.0, but it is recommended that you
update your code to BeanProvider. In addition, a central dispatcher property was available within BeanLoader in 0.6.4. This property has been
removed in 1.0. If a bean or prototype bean requires a dispatcher from Swiz, this is now accomplished using the [Dispatcher] metadata tag:

Removal of static methods

Since an application can now contain multiple instances of Swiz, the static methods on the Swiz class had to be removed. This means that code
relying on static methods such as Swiz.dispatchEvent() must be modified. In 1.0, event dispatching typically uses a dispatcher injected
using the [Dispatcher] metadata tag. This approach causes much less coupling to Swiz and results in a more flexible application. Full details
on the event handling capabilities can be found in the Event Handling section.

Other changes

the [Autowire] metadata tag has been deprecated in favor of [Inject]. [Autowire] will still function in 1.0 but it is recommended
that you update your code to use [Inject].

Presentations
Space to house slide decks and notes from any Swiz presentations given at conferences, user groups, etc.

BFlex - October 25, 2009 - Ben Clinkinbeard

360Flex BOF - March 8, 2010 - Sönke Rohde & John Yanarella

cf.Objective() - April 23, 2010 - Brian Kotek

How To Contribute to Swiz

How to contribute bug fixes and new features

If you are updating the current version:

The easiest way to contribute to swiz is to commit your changes via Git. Just create your own fork of the most recent milestone. Alternatively, you
can create individual patches in Git to target specific bugs. If you've gone the route of updating a fork (recommended), all you need to do is submit
a pull request via GitHub. The next step is to let us know by sending the following information to the swiz team:

URL for your forked repository / or Git patch

Detailed description of your intent
What did you do?
Why did you do it?
Test Cases / Unit Tests - While test cases are optional but they will assist in getting you changes committed. If you provide unit tests,
you're awesome.

If you are updating a version prior to 1.0:

Please don't. But if you must, you should use Subversion (SVN) to create a patch. Unfortunately, we can't guarantee patches for pre-1.0 versions
will be accepted.

How to contribute documentation

If you've written a blog entry or recorded a presentation that you think would be helpful for the swiz community, let us know. We can add the
content to the wiki, merge it into the official swiz documentation or just promote it.
Release Notes
v1.0.0 Release Notes

[Mediate] is now [EventHandler] - To better communicate the intention of the tag and in an effort to standardize AS3 DI metadata,
[Mediate] has been deprecated in favor of [EventHandler]. The syntax and supported attributes are identical, and [Mediate] is still
supported for backwards compatibility, but [EventHandler] is now preferred. Spring ActionScript has always used [EventHandler] for this
purpose.

Smart view tear down - Some actions in an application, like state changes or a container's addition or removal of scrollbars, can cause a
view to be temporarily removed from the display list. Swiz now waits a single frame before tearing down views to avoid incidental tear
downs caused by the events described previously.

ISetUpValidator and ITearDownValidator - These interfaces declare allowSetUp():Boolean and allowTearDown():Boolean methods,
respectively. Implementing one or both will allow your class to opt out of the automatic set up and/or tear down (by returning false) that is
configured for the rest of your application. If you want to opt back in, simply have your class return true for the appropriate method.

Implicit helper class injections - If an [Inject] tag is declared requesting an IServiceHelper, ServiceHelper, IURLRequestHelper,
URLRequestHelper, or MockDelegateHelper by type, Swiz will automatically create beans for the helper classes. As a user you do not
need to declare the helper classes as beans.

ServiceHelper::executeServiceCall() now returns the AsyncToken - Behind the scenes, executeServiceCall() creates and uses an
instance of AsyncToken to wire up your result and fault handlers. This AsyncToken is now returned from the method in order to allow
additional usage as needed.

URLRequestHelper::executeURLRequest() now returns the URLLoader it creates - Similar to the executeServiceCall() change, Swiz
now returns the URLLoader instance it uses in case you need to interact with it.

URLRequestHelper now supports extra handlerArgs - All handler methods specified will receive the same handlerArgs provided to
executeURLRequest().

BeanEvent refinements - BeanEvent now has four distinct types: ADD_BEAN, REMOVE_BEAN, SET_UP_BEAN and
TEAR_DOWN_BEAN. ADD_BEAN will not only set up the attached object (as SET_UP_BEAN does), it will also make it available as a
bean to be injected elsewhere. REMOVE_BEAN is the corresponding type, causing the attached object to be both torn down and
removed from the list of available beans.

Smarter [EventHandler] - The Flash Player's event listening system is, at its core, based on strings. This means that event listeners can
sometimes collide if the event types they are listening for have the same string value. However, if you use the class based syntax for
[EventHandler] (or [Mediate]), Swiz will now prevent these collisions. So if you have [EventHandler( "FooEvent.FOO" )] on one method
and [EventHandler( "BarEvent.FOO" )] on another, Swiz will call the correct one based on the actual type of the event instance, even if
both evaluate to "foo". Sweet!

Better workflow for overriding processors - Needing to override the default processors for tags like [Inject], [PostConstruct] and the
others is extremely rare. At the same time, we weren't happy with the cumbersome workflow for doing so. The process has been
improved to simply use processor priorities as a unique list. If you provide a custom processor whose priority matches a built-in
processor's, Swiz will replace the built-in processor with your own.

Chaining API enhancements - This is perhaps the most significant and exciting change since the RC2 release. See the wiki for more
info. http://swizframework.jira.com/wiki/display/SWIZ/Chaining+API

Miscellaneous optimizations and bug fixes - There have also been countless refinements, optimizations and bug fixes in order to
ensure this is a fast, solid framework. Check it out and let us know what you think!

For a complete list of changes made for this release see this compare view.

v1.0.0-RC2 Release Notes

Automatic Swiz tear down - When the dispatcher for a Swiz instance is torn down, the Swiz instance itself will automatically be torn
down as well, performing all necessary cleanup for the objects it manages. Practically speaking, this means that when you define a Swiz
instance within a module or child view, simply removing it from the display list will cause Swiz to clean up the instance for you.

Performance and Memory improvements - We made it so Swiz's reflection system only captures and stores the metadata references it
cares about. In many cases this has the effect of reducing the memory footprint of the reflection system by as much as 90%!

IServiceHelper and IURLRequestHelper - We took some good advice from the community and created IServiceHelper and
IURLRequestHelper interfaces. Aside from just being good form, this will increase the testability of classes that use these helpers by
allowing stub implementations to be provided under test.

ServiceHelper improvements - We also improved ServiceHelper by extending the ability to have extra arguments passed to your
handler to include fault handlers. Result handlers have always had this ability and it can be extremely useful. Just like with result
handlers, Swiz detects this automatically based on your method signature. Lastly, ServiceHelper::executeServiceCall() now returns the
ASyncToken that is passed into the method.
 Chaining API refinements - The Chaining API has been cleaned up to be more consistent and better support chain nesting. This is a
very powerful API with near limitless possibilities. For a great (brief) introduction, see
http://www.riaspace.com/2010/08/swiz-1-0-chaining-api-explained/

Miscellaneous bug fixes - We fixed some minor issues with the tear down of pop ups and two way bindings, as well as other small
improvements.

Metadata processor ordering - Metadata processors (both built-in and custom) are now sorted in descending order by their priority to
more closely match the way event listener priorities work. We also tweaked the order of our built-in processors so that [PreDestroy]
methods will actually run before an object's injections have been cleared.

CommandMap - Swiz now provides official, built-in support for the Command pattern! CommandMap is a new class that can be
extended and dropped right into a BeanProvider. From the commit message: "Added CommandMap functionality to ease migration from
frameworks like Cairngorm, and to accommodate developers/teams that may prefer the Command pattern. Our implementation borrows
heavily from Robotlegs (robotlegs.org), because their implementation was clean and in line with our goals." Look for a blog post soon
showing how to use this new feature!

IBeanFactory cleaned up - BeanFactory is really the heart of Swiz. It is responsible for boot strapping Swiz instances and generally
managing the IoC container. We have cleaned up its IBeanFactory interface to be more consistent and predictable.

BeanEvent additions - Related to the IBeanFactory upgrades, we have improved BeanEvent as well. BeanEvent has been around for a
while, with constants for SET_UP_BEAN and REMOVE_BEAN. Dispatching a BeanEvent with one of these types and an object instance
attached would, respectively, set up (provide the dependencies and process the metadata declared by the object) or tear down (clear out
the injected dependencies) the object. Part of the IBeanFactory improvements, however, were the distinctions between bean set up and
tear down, and bean addition and removal. Adding a bean makes it available for injection into other objects, removing it makes it
unavailable for injection. In order to allow all of these actions to be triggered by an event, we've added ADD_BEAN and REMOVE_BEAN
to BeanEvent. One last note is that adding a bean will also set up that bean, but the opposite is not true; you can set up an object without
making it available for others to inject. On the other end of the lifecycle, removing a bean will always tear the bean down, but tearing
down does not imply removal. Among other reasons, this is because views may be removed from the stage and re-added, causing them
to be torn down and then set up again.

For a complete list of changes made for this release see this compare view.

v1.0.0-RC1 Release Notes

[Dispatcher], IDispatcherAware - You get a reference to the Swiz dispatcher either by decorating a property of type IEventDispatcher
with [Dispatcher] or by implementing the IDispatcherAware interface. When using [Dispatcher] you can provide a scope attribute and give
it a value of either "global" or "local". Global is the default and will provide you the shared dispatcher from the root Swiz instance. Local
will give you the shared dispatcher from the Swiz instance that directly contains your object. Using the local dispatcher allows you to
confine events to a child Swiz instance, such as within a module.

scope attribute on [Mediate] - Directly corresponds to the dispatchers discussed in the point above. This allows you to mediate events
dispatched either by the local shared dispatcher or by the root dispatcher.

SourceMate config file - SourceMate is a great plug-in for FlashBuilder, and one of its features is metadata code completion. We have
provided a config file you can import to automatically get this feature for all supported Swiz tags. It can be found at
http://github.com/swiz/swiz-framework/blob/master/misc/SwizMetadataSourceMateConfig.xml

injectionEvent -> setUpEventType, etc. - The event handlers that Swiz uses to set up and tear down your views is now completely
configurable. setUpEventType, setUpEventPhase, setUpEventPriority, tearDownEventType, tearDownEventPhase and
tearDownEventPriority directly correspond to the values used in the listener creation by Swiz.

[PreDestroy] and IDisposable - You can use these to define code that should be run when tearing down your views such as cleaning up
listeners or setting references to null. Note that this is called in response to the event specified by tearDownEventType, so when using
the default of removedFromStage, your view will already be off of the display list by the time these methods are called.

IInitializing.init -> IInitializing.afterPropertiesSet() - To avoid conflict with UIComponent's method of the same name and to stay more
consistent with Spring, the init() method of IInitializing has been changed to afterPropertiesSet().

Ant build - Full Ant build support!

Custom namespaces - This is pretty sweet. Swiz can now address code defined in custom namespaces automatically. If you cringe at
having to make properties and methods public this feature is for you. Note that due to Flash Player restrictions we still cannot reach
protected or private members, but we feel this is a really good compromise. Also note that Flex is not able to bind to non-public members.

Module and child Swiz support - You can now define child Swiz instances. This is very useful for modules, or potentially even deep
dark views that users may never open in your application. When a Swiz instance is created it will dispatch a bubbling event from its host
view component that will be caught by a parent Swiz instance further up the display list. A parent/child relationship is then established,
allowing the child to inherit beans and configuration settings from its parent.

AIR window support - Support for separate native windows in AIR has been restored. To make this work you call
swizInstance.registerWindow( myNewWindow ) before opening the window via myNewWindow.open(). This will allow Swiz to manage
the window and its descendant views, and works by creating a Swiz instance inside the window and making swizInstance its parent.
 View injection changes - Mediate now supports useCapture, which can be useful when using the mediator or passive view pattern. See
http://www.webappsolution.com/wordpress/2010/04/20/swiz-10-rc1-removes-autowire-viewtrue-requires-new-abstractviewmediator/ for
more info.

Removed Outject - This turned out to be a bad idea so we yanked it.

Util classes renamed to helpers - ServiceRequestUtil and URLRequestUtil have been renamed to ServiceHelper and
URLRequestHelper, respectively.

Chain API changes/updates - The chaining API has been cleaned up and made more consistent. IAutonomousChainStep has been
added, which is an interface you can use to define steps that can execute themselves. The built in CommandChain and EventChain
classes include support for these kinds of steps.

BeanEvent - BeanEvents can be used to manually control the injection and tear down phases for views and objects you attach to the
event. Dispatching BeanEvent.SET_UP_BEAN will trigger Swiz to pass an object through it's injection and mediator processors.
Dispatching BeanEvent.TEAR_DOWN_BEAN will trigger Swiz to remove any mediators and injection bindings it has created.

Removed setUpMarkerFunction - We briefly provided a way for users to determine whether or not a view should be wired up. This has
been removed so that a proper, more robust API can be implemented in the future.

[Inject( bind="false" )] - Previously, when injecting bean properties with a tag like [Inject( "myModel.someProp" )], Swiz would create a
binding if the source property was bindable. We have changed the default behavior so to make you choose to create bindings if you need
them. To make Swiz to create a binding for you, you must set bind to true in the metadata tag. [Inject( "myModel.someProp", bind="true"
)]. In general, using Inject with bindings should be treated carefully. We would like to discourage it's overuse, particularly in situations
where users are creating global variables for their applications through the Inject tag.

For a complete list of changes made for this release see this compare view.

External Community Resources

Blog Posts and Tutorials

Swiz blog category at briankotek.com
Swiz blog category at flex-blog.com
A look at a URLMapping custom metadata processor

Example Applications or Extensions

View mediator custom metadata processor
foomonger's metadata processors, inlcuding MediateSignal and Logger