Package | org.spicefactory.parsley.core.context |
Interface | public interface Context extends flash.events.IEventDispatcher |
Implementors | DefaultContext |
It is recommended that you avoid to work with the Context API directly in regular application development. Parsley is designed in a way that helps you keep your objects decoupled from the framework (and decoupled from each other). Thus you should probably prefer working with the Parsley Manual over using these Framework API Docs.
But if you are extending or modifying the framework, building your own framework on top of Parsley or just creating a bunch of custom configuration tags, it is likely that you need access to the Context.
There are two ways to get access to a Context:
FlexContextBuilder.build()
or
XmlContextBuilder.build()
always returns a Context instance, although in most cases you'll simply
ignore the returned instance.[Inject]
metadata tag and will get the Context they
belong to injected upon object creation.All builtin Context implementations like DefaultContext
, ChildContext
or
DefaultDynamicContext
use an ObjectDefinitionRegistry
internally. Thus with all
builtin Context implementations you'll be able to work with all MXML, XML or Metadata tags that map
to classes implementing ObjectDefinitionDecorator
.
But implementations of this interface are not required to work with ObjectDefinitions
,
for special requirements you can create custom implementations from scratch.
Context instances returned by the various ContextBuilder entry points may not be fully initialized yet,
depending on whether the configuration mechanism used operates synchronously or asynchronously, and whether
the Context contains object which are defined to be asynchronously initializing (e.g. through the [AsyncInit]
metadata tag.
You can check the state of a Context instance through its configured
and initialized
properties.
The former is set to true as soon as all configuration artifacts have been processed (e.g. loading XML files, reflecting
on MXML configuration classes and so on). The latter will be set to true after all objects configured to be non-lazy
singletons have been instantiated and fully configured, including objects configured for asynchronous initialization.
Property | Defined By | ||
---|---|---|---|
configured : Boolean [read-only]
Indicates whether configuration for this Context has been fully processed. | Context | ||
destroyed : Boolean [read-only]
Indicates whether this Context has been destroyed. | Context | ||
domain : ApplicationDomain [read-only]
The ApplicationDomain used to reflect on instance of this Context. | Context | ||
initialized : Boolean [read-only]
Indicates whether this Context has been fully initialized. | Context | ||
parents : Array [read-only]
All parent Contexts that this Context inherits from. | Context | ||
scopeManager : ScopeManager [read-only]
The scope manager that handles all scopes that this Context belongs to. | Context | ||
viewManager : ViewManager [read-only]
The view manager used to dynamically wire view instances to this Context. | Context |
Method | Defined By | ||
---|---|---|---|
Creates an object from the specified definition and dynamically adds it to the Context. | Context | ||
Dynamically adds the specified instance to the Context. | Context | ||
containsObject(id:String):Boolean
Checks whether this Contex contains an object with the specified id. | Context | ||
createDynamicObject(id:String):DynamicObject
Returns a new dynamic object for the specified id. | Context | ||
createDynamicObjectByType(type:Class):DynamicObject
Returns a new dynamic object for the specified type. | Context | ||
destroy():void
Destroys this Context. | Context | ||
findAllDefinitionsByType(type:Class, status:LookupStatus = null):Array
Returns all definitions for the specified type. | Context | ||
Returns the definition for the object with the specified id or null if no such object exists. | Context | ||
Returns one definition for the specified type. | Context | ||
getAllObjectsByType(type:Class):Array
Returns all objects that match the specified type. | Context | ||
getObject(id:String):Object
Returns the singleton object with the specified id. | Context | ||
getObjectByType(type:Class):Object
Returns a singleton object of the specified type. | Context | ||
getObjectCount(type:Class = null):uint
Returns the number of objects in this Context that match the specified type. | Context |
Event | Summary | Defined By | ||
---|---|---|---|---|
Dispatched when configuration for this Context has been fully processed. | Context | |||
Dispatched when the Context was destroyed. | Context | |||
Dispatched when Context initialization failed. | Context | |||
Dispatched when the Context was fully initialized. | Context |
configured | property |
configured:Boolean
[read-only]
Indicates whether configuration for this Context has been fully processed.
This includes loading configuration files, reflecting on classes, processing metadata tags
or validating the configuration. After this property is set the configuration of the Context
is sealed an can no longer be modified. If you try to access the content of this Context
with methods like getObject
before this property has been set to true, an Error
will be thrown. In case this property is set to false after Context creation you can listen
to the ContextEvent.CONFIGURED
event.
public function get configured():Boolean
destroyed | property |
destroyed:Boolean
[read-only] Indicates whether this Context has been destroyed. When this property is set to true, the Context can no longer be used and most of its methods will throw an Error.
public function get destroyed():Boolean
domain | property |
domain:ApplicationDomain
[read-only] The ApplicationDomain used to reflect on instance of this Context.
public function get domain():ApplicationDomain
initialized | property |
initialized:Boolean
[read-only]
Indicates whether this Context has been fully initialized. This includes processing the configuration
(thus configured
is always true if this property is true) and instantiating all objects
that were configured as non-lazy singleton (the default). This includes processing all objects which
were configured to be asynchronously initializing, waiting until all these objects have been fully
initialized. In case this property is set to false after Context creation you can listen
to the ContextEvent.INITIALIZED
event.
The objects contained in this Context can already be accessed before this property is set to true (as long
as the configured
property is set to true). This is necessary since objects that are instantiated and
configured during the initialization process of the Context may need access to their dependencies.
But you should be aware that you might mix up the initialization order so you should use the Context with
caution before this property is set to true.
public function get initialized():Boolean
parents | property |
parents:Array
[read-only] All parent Contexts that this Context inherits from.
public function get parents():Array
scopeManager | property |
scopeManager:ScopeManager
[read-only] The scope manager that handles all scopes that this Context belongs to. This includes scopes inherited from parent Contexts as well as scopes created for this Context.
public function get scopeManager():ScopeManager
viewManager | property |
viewManager:ViewManager
[read-only] The view manager used to dynamically wire view instances to this Context.
public function get viewManager():ViewManager
addDynamicDefinition | () | method |
public function addDynamicDefinition(definition:DynamicObjectDefinition):DynamicObject
Creates an object from the specified definition and dynamically adds it to the Context.
Parameters
definition:DynamicObjectDefinition — the definition to create an object from
|
DynamicObject — an instance representing the dynamically created object and its definition
|
addDynamicObject | () | method |
public function addDynamicObject(instance:Object, definition:DynamicObjectDefinition = null):DynamicObject
Dynamically adds the specified instance to the Context.
Parameters
instance:Object — the object to add to the Context
| |
definition:DynamicObjectDefinition (default = null ) — optional definition to apply to the existing instance
|
DynamicObject — an instance representing the dynamically created object and its definition
|
containsObject | () | method |
public function containsObject(id:String):Boolean
Checks whether this Contex contains an object with the specified id.
Parameters
id:String — the id to check
|
Boolean — true if this Context contains an object with the specified id
|
createDynamicObject | () | method |
public function createDynamicObject(id:String):DynamicObject
Returns a new dynamic object for the specified id. Throws an Error if no such object exists.
Dynamic objects can only be created from DynamicObjectDefinitions, such as those created
by the <DynamicObject>
MXML tag or the <dynamic-object>
XML tag.
Parameters
id:String — the id of the object
|
DynamicObject — a new dynamic object for the specified id
|
createDynamicObjectByType | () | method |
public function createDynamicObjectByType(type:Class):DynamicObject
Returns a new dynamic object for the specified type.
This method will throw an Error if no object with a matching type exists in this Context
or if it finds more than one match.
Dynamic objects can only be created from DynamicObjectDefinitions, such as those created
by the <DynamicObject>
MXML tag or the <dynamic-object>
XML tag.
Parameters
type:Class — the type of the object to return
|
DynamicObject — a new dynamic object for the specified type
|
destroy | () | method |
public function destroy():void
Destroys this Context. This includes processing all lifecycle listeners for all objects that this
Context has instantiated and calling their methods marked with [Destroy]
.
The Context may no longer be used after calling this method.
findAllDefinitionsByType | () | method |
public function findAllDefinitionsByType(type:Class, status:LookupStatus = null):Array
Returns all definitions for the specified type.
Parameters
type:Class — the type of the objects to return
| |
status:LookupStatus (default = null ) — internal status to avoid duplicate lookups, not used in normal application code
|
Array — all definitions for the specified type
|
findDefinition | () | method |
public function findDefinition(id:String, status:LookupStatus = null):ObjectDefinition
Returns the definition for the object with the specified id or null if no such object exists.
Parameters
id:String — the id of the object
| |
status:LookupStatus (default = null ) — internal status to avoid duplicate lookups, not used in normal application code
|
ObjectDefinition — the definition for the object with the specified id or null
|
findDefinitionByType | () | method |
public function findDefinitionByType(type:Class, status:LookupStatus = null):ObjectDefinition
Returns one definition for the specified type. Throws an Error if there is more than one definition for the specified type. If this Context has parents, it should only look into parent Contexts if the definition cannot be found in the local Context.
Parameters
type:Class — the type of the object to return
| |
status:LookupStatus (default = null ) — internal status to avoid duplicate lookups, not used in normal application code
|
ObjectDefinition — one definition for the specified type
|
getAllObjectsByType | () | method |
public function getAllObjectsByType(type:Class):Array
Returns all objects that match the specified type. This includes subclasses or objects implementing the interface in case the type parmeter is an interface. When no match is found an empty Array will be returned.
Parameters
type:Class — the type of the objects to return
|
Array — all objects that match the specified type
|
getObject | () | method |
public function getObject(id:String):Object
Returns the singleton object with the specified id. Throws an Error if no such object exists.
Parameters
id:String — the id of the object
|
Object — the object with the specified id
|
getObjectByType | () | method |
public function getObjectByType(type:Class):Object
Returns a singleton object of the specified type. This method will throw an Error if no object with a matching type exists in this Context or if it finds more than one match.
Parameters
type:Class — the type of the object to return
|
Object — an object of the specified type
|
getObjectCount | () | method |
public function getObjectCount(type:Class = null):uint
Returns the number of objects in this Context that match the specified type. If the type parameter is omitted the number of all objects in this Context will be returned.
Parameters
type:Class (default = null ) — the type to check for matches
|
uint — the number of objects in this Context that match the specified type
|
configured | Event |
org.spicefactory.parsley.core.events.ContextEvent
org.spicefactory.parsley.core.events.ContextEvent.CONFIGURED
Dispatched when configuration for this Context has been fully processed. This includes loading configuration files, reflecting on classes, processing metadata tags or validating the configuration. After this property is set the configuration of the Context is sealed an can no longer be modified.
Some ContextBuilder implementations excute synchronously. In this case this
event will never fire. Thus before registering for this event you should check the
configured
property on the Context.
ObjectDefinition
instances have been frozen and cannot be
modified anymore. Context.getObject
and other methods of
the Context can now be called. But application code should be careful
to fetch objects from the container before the INITIALIZED
event because it could alter the sequence of asynchronously initializing
objects. Nevertheless it is legal to fetch objects at this point because
the asynchronously initializing objects might have dependencies themselves.
destroyed | Event |
org.spicefactory.parsley.core.events.ContextEvent
org.spicefactory.parsley.core.events.ContextEvent.DESTROYED
Dispatched when the Context was destroyed. At this point all methods marked with [Destroy] on objects managed by this context have been invoked and any child Context instances were destroyed, too.
Constant for the type of event fired when a Context instance was destroyed.error | Event |
flash.events.ErrorEvent
flash.events.ErrorEvent.ERROR
Dispatched when Context initialization failed. This may happen due to errors in processing the configuration or because some asynchronous initializer on a non-lazy singleton failed. All objects that have already been created at this point (partly or fully) will get their PreDestroy methods invoked.
After the INITIALIZED
event of this Context has fired and the
initialized
property was set to true, this event can never fire.
In particular it does not fire if retrieving a lazy initializing object fails
after Context initialization.
initialized | Event |
org.spicefactory.parsley.core.events.ContextEvent
org.spicefactory.parsley.core.events.ContextEvent.INITIALIZED
Dispatched when the Context was fully initialized. At this point all configuration was processed and all non-lazy singleton objects in this Context have been instantiated and configured and their asynchronous initializers (if any) have successfully completed.
Some ContextBuilder implementations execute synchronously. In this case this
event will never fire. Thus before registering for this event you should check the
initialized
property on the Context.