Sodality is a runtime AOP (Aspect Oriented Programming) library for ActionScript 3. Simple implementations of Sodality use Metadata to call functions at specific times. Because of this, simple usage is only possible in IDEs that allow custom Metadata (e.g. Flex, FDT, FlashDevelop, etc), although it can be used in a more advanced manner in Flash (and others which don’t allow custom Metadata).

Simply put, Sodality is like an event system, allowing functions to get called in any part of your application when another piece of code dispatches an Advice object.

1. Basic Example
2. Basic Concepts
3. Simple Usage
4. A Real Example
5. Further Flexibility
6. Download Source
   

1. Basic Example

If somewhere within your app an Advisor class (more on that soon) dispatched a MouseClickAdvice object (for example), like this:

	dispatchEvent(new MouseClickAdvice(this, mouseX, mouseY));

Any other Advisor could catch the MouseClickAdvice like this (the bracketed metadata is what does the magic):

	[Trigger(timing="before")]
	public function onMouseClickAdvice(cause:IMouseClickAdvice):void{
		trace("Something was clicked at: "+cause.mouseX,cause.mouseY);
	}

Or, it could catch the MouseClickAdvice asynchronously (allowing it to take some time before any other Advisors catch the advice) like this:

	private var advice:AsyncMethodAdvice;

	[Trigger(timing="before")]
	public function onMouseClickAdvice(cause:IMouseClickAdvice,
					advice:AsyncMethodAdvice):void{
		/* The advice has been caught here, I'm going
		to wait 1 second before allowing it to continue.*/
		this.advice = advice;
		var timer:Timer = new Timer(1000,1);
		timer.addEventListener(TimerEvent.TIMER, onTimer);
	}
	public function onTimer(event:TimerEvent):void{
		trace("I'll now allow the advice to continue");
		advice.adviceContinue();
	}

2. Basic Concepts

The President

Every Sodality Application has (at least) one President, the President monitors and arranges all Sodality processes. Whilst the president doesn’t get used directly by your code to give Sodality the scope of it’s operations. The President must have a reference to some top level DisplayObject, this allows it to detect Advisors being added or removed from the app, usually this is set to the root of your app.

The Advisors

Any class can become an Advisor by implementing the IAdvisor interface, this allows it to specify Metadata above it’s functions telling Sodality when to call the function. In most apps, IAdvisor is only implemented by DisplayObjects which get added to the stage, non-visual advisors normally extend the DynamicAdvisor class, which allows them to be easily added to the President.

The Advice

Each Advice object represents an operation which will be executed, Advice objects are dispatched like events from any IAdvisor. Normally, each type of request will have an interface associated with it, the Advisors then will listen for the interface (rather than the class) which allows any Advice class to implement as many of these request types as required.

3. Simple Usage

Normally, Sodality is used for broad-scale communication between parts of an application. There are reusable DynamicAdvisors which specify several Advice interfaces allowing your app to instruct the DynamicAdvisor how to behave.

A good example of this would be the SoundAdvisor, which is used to play sounds, adjusting each sound’s volume appropriately and making sure the wrong sounds do not overlap. The SoundAdvisor specifies many Advice interfaces (e.g. IAddSoundAdvice, IRemoveSoundAdvice, IChangeVolumeAdvice, etc.), each of these correspond to a method within the SoundAdvisor. When an Advice object that implements one of these interfaces gets dispatched from another Advisor the SoundAdvisor’s corresponding method will be called and it will have an opportunity to make the required changes (e.g. begin playing a sound, adjust the volume etc.). These Advice interfaces can specify any functions or getters that the SoundAdvisor requires to complete the request, for example, the IChangeVolumeAdvice could look something like this:

package examplePackage
{
	import org.farmcode.sodality.advice.IAdvice;
	
	public interface IChangeVolumeAdvice extends IAdvice
	{
		function get volume(): Number;
		function get muted(): Boolean;
	}
}

This means that whenever an Advice object implements the IChangeVolumeAdvice interface, it must specify a volume and whether the SoundAdvisor should be muted, which is all the information that the SoundAdvisor needs to complete the request. The reason that interfaces are used instead of classes is so that each Advice object can implement many different interfaces, which will each execute different requests across different Advisors.

4. A Real Example

Stay tuned, we’ll be posting a real example with source code very soon.

5. Further Flexibility

Sodality has been built to be flexible, there are still unexplored pieces of flexibility within it’s architecture, we’d love to see how other people use Sodality and where it goes from here. These are some examples of under-explored areas in Sodality:

IAdviceTrigger

IAdviceTriggers are the object which tie pieces of advice together, they’re a powerful tool which is usually hidden from view, they can dramatically change the functionality of Sodality.

President Monitors

Because of the Asynchronous way that Sodality runs, classes which affect/monitor the running of Sodality can easily be plugged in. Here are some examples of tools we’ve built on to this:

• A (faux) threading system, which allows different advice streams to take up different amounts of processing time.
• A step-through debugger
• A hot-key which traces out any currently pending advice.

Whilst we haven’t open-sourced these, they are good examples of the types of options that are available.

6. Download Source

This is part one of a three part tutorial.

SiteStream is an AS3 library for parsing XML into first-class objects. All the information needed for the parsing process is in the XML syntax and there is no need to write any additional code.
XML data sources can reference each other, allowing data to load in piece by piece depending on what your flash app requires.
SiteStream also has the powerful feature of being able to specify other SWFs which contain the classes used, so that your class libraries are loaded invisibly only when required.

1. Simple XML Syntax Example
2. Retrieving an item
3. Download Source

1. Simple XML Syntax Example

SiteStream XML allows you to write object structures in XML format. Each XML Node represents an Actionscript object.

Look at the first child tag in the XML below, it has the following characteristics:

• It’s node name “Shape” is the name of the Class which will be used for this object
• It’s namespace “displayPackage” is a package identifier, all package identifiers have a listing in the root tag which specifies the full package for the class.
• It has an attribute “id” with the value “mask”, this specifies both the property of the parent object that this object should fill and the SiteStream name used in SiteStream paths.
• It has an attribute “alpha” with a value “0.5”, this is how simple properties are set into objects.

This example creates a Sprite, it then creates a Shape and sets it as the Sprite's mask, then it creates a Rectangle (100x100) which it sets as the Shape's scrollRect.

<displayPackage:Sprite id="root"
	displayPackage="flash.display.*"
	geomPackage="flash.geom.*"
	>
	<displayPackage:Shape id="mask" alpha="0.5">
		<geomPackage:Rectangle id="scrollRect" x="0" y="0" width="100" height="100"/>
	</displayPackage:Shape>
</displayPackage:Sprite>

2. Retrieving an item

The following example has an XML data source which creates an array of MyClass objects (an arbitrary class as an example), the code shows how an item could be retrieved from the array. Notice that the class must be included in the code (more on that in Part 2). The MyClass Class can be seen at the bottom of this post.

myXML.xml:

<Array id="root"
	myPackage="myPackage.*">
	<myPackage:MyClass id="item1"/>
	<myPackage:MyClass id="item2"/>
	<myPackage:MyClass id="item3"/>
	<myPackage:MyClass id="item4"/>
	<myPackage:MyClass id="item5"/>
</Array>

SiteStreamTest.as:

package
{
	import org.farmcode.siteStream.SiteStream;
	import flash.display.Sprite;
	import myPackage.MyClass;
	public class SiteStreamTest extends Sprite
	{
		public function SiteStreamTest(){
			var includeClass:Class = MyClass;
			var siteStream:SiteStream = new SiteStream();
			siteStream.rootURL = "myXML.xml";
			siteStream.getObject("root/item2",onSuccess);
		}
		private function onSuccess(e:MyClass):void{
			trace("Item 2 retrieved");
		}
	}
}

MyClass.as:

package myPackage

{
	public class MyClass
	{
		public var colour:Number;
		public var childObject:MyClass;
	}
}

3. Download Source

Goto Tutorial 2 >

  A tiny bit of research into rendering cylinders in actionscript (using a displacement filter) has resulted in this example.

For the sake of anyone out there who is interested in building a renderer for PV3D (or any of the AS3 3D engines) I have included the class code (it won't compile without our supporting libraries, but it will give you an idea how it's done).