PureMVC Standard for AS3

Release Notes

Pre-2.0 installations should read on for migration information and changes on the 2.0 line.

Summary of Changes in 2.0.4

This release fixes the only two outstanding bugs.

• Dissallowed  re-registration of Mediators in View.registerMediator.
• Modified View.notifyObservers to notify from a copy of the observer list rather than the actual observer list, which may  change during the notification loop.

Summary of Changes in 2.0.3

This release replaces an interface method was inadvertently removed in 2.0 of the AS3 Standard Version. This bug affected people who send custom Notifications via the Facade. You can read about on  this forum post. This is a transparent fix that requires no migration if you already have 2.0.1 installed.

• The notifyObservers method was added back to IFacade.

Summary of Changes in 2.0.2

This relesae fixes an outstanding bug with removing and re-registering Commands on the AS3 Standard Version, which you can read about on  this forum post. This is a transparent fix that requires no migration if you already have 2.0.1 installed.

• Refactored View.removeMediator method, moving the logic for removing an Observer into a removeObserver method (also on IView), which is now called by the Controller.removeCommand method as well as the View.removeMediator method.

• The Proxy.removeProxy method only attempts to remove the Proxy if it is registered. This could've caused a problem if you tried to remove a Proxy that was not registered.

Summary of Changes in 2.0.1

This release adds complementary methods to the Proxy that were added to Mediator when the 2.0 release was made in limited form. This is a transparent upgrade that requires no migration if you already have 2.0.1 installed.

• Proxy gets onRegister and onRemove methods. These methods are called when an IProxy is registered. Proxies previously had no knowledge of when they were registered or removed. This functionality allows a Proxy to notify other parts of the system when it becomes available, or to remove listeners and null its view component or data object after being removed, so that it can be garbage collected.

Summary of Changes in 2.0

This release breaks backward compatibility with any previous release. Migration is a very simple process, outlined clearly below. The package structure has changed to incorporate the language for this release. With all of the framework ports that are being done it is imperative that all code, in any context be clear in the package name alone which language it was written for.

That much being a given, it seemed this was the best time to make any further changes that would entail a migration. The only change made here that is truly backward-incompatible is the Mediator naming strategy. It now works just like Proxy.

There is a minor bugfix, and otherwise, most of these changes simply round out the API with what should've been there before. For instance, you can now check to see if a given Command, Mediator or Proxy is registered. And now a Mediator or Proxy is made aware when it is registered or removed.

We now return you to a staunch policy of 'No New Features, Only Bug Fixes!!!'

• Package name includes now language. the org.puremvc.* namespace is now org.puremvc.as3.*

• The Mediator naming scheme changed to match that of the Proxy. Now the constructor to the Mediator takes a mediatorName argument before the viewComponent argument. This means that you no longer need to override the getMediatorName method in your Mediators, you merely send the name to super to be set in the constructor. This should reduce confusion about the naming strategy of the two boundary counterparts Proxy and Mediator. They both work the same now.

• The Mediator now has a setViewComponent method. This means that transient view components are now supported. Previously, a Mediator was forever bound to its viewComponent given at construction. There was no way to set the viewComponent thereafter. This was by design, but it turned out not to provide any real benefit, and in fact hampered some reasonable view management schemes. Now you may replace a Mediator's view component at any time, or create a Mediator and then 'lazily' create its view component at a later time.

• The Model, View and Facade removeProxy and removeMediator methods now return a reference to the Proxy or Mediator that was removed from the Model or the View. This supports dynamic unregistration and reregistration of Proxies and Mediators. This means you can make Proxies and Mediators unavailable to the rest of the system by notification or retrieval for some amount of time, store them somewhere, and then make them available at some later time by registering them again.

• Model and Facade get a hasProxy method; View and Facade get a hasMediator method. In an application that dynamically registers and unregisters resources, you may need to check and see if a given Mediator or Proxy is registered before attempting to create and register it or retrieve and use it.

• Mediator and gets onRegister and onRemove methods. These methods are called when an IMediator is registered. Mediators previously had no knowledge of when they were registered or removed. This functionality allows a Mediator to notify other parts of the system when it becomes available, or to remove listeners and null its view component or data object after being removed, so that it can be garbage collected.

• The Facade now implements INotifier, implementing a sendNotification method. This means that you never have to create a Notification inside a Facade method and then call notifyObservers, you may simply call sendNotification with the parameters in the same way that Commands, Mediators and Proxies do. The notifyObservers method is left public in the Facade only so that you may still create and send instances of custom Notification classes. It also facilitates an even cleaner implementation of the 'facade.startup(this)' startup idiom.

• Notifier's sendNotification method now calls facade.sendNotification instead of notifyObservers. There is no longer any reason to call facade.notifyObserver from anywhere unless you are implementing custom Notification classes. Therefore, the Notifier class simply passes through the parameters to the Facade's sendNotification method where the actual notification is created and notifyObservers is called. Also, Notifier now implements the INotifier interface, which was present before but not referred to with 'implements'.

• Model, View and Controller classes are moved into the same package. Previously these classes were in separate packages under core. They now reside in the same package and so may share internal properties. Use of the Facade class in PureMVC applications should render this change completely transparent to your application. Only if you manipulate these classes directly, will you need to your modify import statements.

• All interfaces have been updated to reflect the above changes where necessary. Additionally, the IProxy interface has been updated to include the missing setData and getData methods which are present on Proxy.

• A bug in the Notification.toString implementation was fixed. A corresponding unit test was added to NotificationTest. For discussion of the bug see  this forum topic.

To migrate an application written for a prior version of PureMVC for AS3

After replacing your old PureMVC.swc (or source code tree) with the 2.0 version:

1. Globally Find and Replace 'org.puremvc' with 'org.puremvc.as3' in all your source code. This should only affect imports.
2. In the constructor of all Mediator subclasses, pass the mediator name to super as the first argument. Your mediator constructor signature doesn't have to change, you simply have to pass a name to Mediator superclass inside your constructor now. Usually this is a matter of changing 'super(viewComponent)' to 'super(NAME, viewComponent)'. However if your viewComponent provides a unique name which your Mediator subclass instance will use to register itself, you might change 'super(viewComponent)' to 'super(viewComponent.id, viewComponent)'.
3. Remove getMediatorName() methods from Mediator subclasses. This is implemented properly in the base class and does not have to be overridden.
4. Refactor any calls to facade.notifyObservers to use facade.sendNotification instead. Remove any now-unneeded Notificaton creation; you only need to be passing the arguments to sendNotification, not a complete notification instance. Note that you should skip this step if you are creating and sending an instance of a custom Notification class.