Skip to content
This repository has been archived by the owner on Jul 3, 2019. It is now read-only.

Commit

Permalink
Added AsDoc comments for lots of methods in Injector and some other c…
Browse files Browse the repository at this point in the history 
…lasses
  • Loading branch information
@tschneidereit
tschneidereit committed Oct 28, 2011
1 parent 6d44ee7 commit 21051a0
Show file tree
Hide file tree
Showing 3 changed files with 144 additions and 55 deletions.
10 changes: 10 additions & 0 deletions src/avmplus/DescribeTypeJSON.as
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,16 @@

package avmplus
{
/**
* Makes the hidden, inofficial function describeTypeJSON available outside of the avmplus
* package.
*
* <strong>As Adobe doen't officially support this method and it is only visible to client
* code by accident, it should only ever be used with runtime-detection and automatic fallback
* on describeType.</strong>
*
* @see http://www.tillschneidereit.de/2009/11/22/improved-reflection-support-in-flash-player-10-1/
*/
public class DescribeTypeJSON
{
//---------------------- Public Properties ----------------------//
Expand Down
186 changes: 134 additions & 52 deletions src/org/swiftsuspenders/Injector.as
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,119 +26,122 @@ package org.swiftsuspenders
/**
* This event is dispatched each time the injector instantiated a class
*
* At the point where the event is dispatched none of the injection points have been processed.
* <p>At the point where the event is dispatched none of the injection points have been processed.</p>
*
* The only difference to the <code>PRE_CONSTRUCT</code> event is that
* <p>The only difference to the <code>PRE_CONSTRUCT</code> event is that
* <code>POST_INSTANTIATE</code> is only dispatched for instances that are created in the
* injector, whereas <code>PRE_CONSTRUCT</code> is also dispatched for instances the injector
* only injects into.
* only injects into.</p>
*
* This event is only dispatched when there are one or more relevant listeners
* attached to the dispatching injector.
* <p>This event is only dispatched when there are one or more relevant listeners attached to
* the dispatching injector.</p>
*
* @eventType org.swiftsuspenders.InjectionEvent
* @eventType org.swiftsuspenders.InjectionEvent.POST_INSTANTIATE
*/
[Event(name='postInstantiate', type='org.swiftsuspenders.InjectionEvent')]
/**
* This event is dispatched each time the injector is about to inject into a class
*
* At the point where the event is dispatched none of the injection points have been processed.
* <p>At the point where the event is dispatched none of the injection points have been processed.</p>
*
* The only difference to the <code>POST_INSTANTIATE</code> event is that
* <p>The only difference to the <code>POST_INSTANTIATE</code> event is that
* <code>PRE_CONSTRUCT</code> is only dispatched for instances that are created in the
* injector, whereas <code>POST_INSTANTIATE</code> is also dispatched for instances the
* injector only injects into.
* injector only injects into.</p>
*
* This event is only dispatched when there are one or more relevant listeners
* attached to the dispatching injector.
* <p>This event is only dispatched when there are one or more relevant listeners attached to
* the dispatching injector.</p>
*
* @eventType org.swiftsuspenders.InjectionEvent
* @eventType org.swiftsuspenders.InjectionEvent.PRE_CONSTRUCT
*/
[Event(name='preConstruct', type='org.swiftsuspenders.InjectionEvent')]
/**
* This event is dispatched each time the injector created and fully initialized a new instance
*
* At the point where the event is dispatched all dependencies for the newly created instance
* <p>At the point where the event is dispatched all dependencies for the newly created instance
* have already been injected. That means that creation-events for leaf nodes of the created
* object graph will be dispatched before the creation-events for the branches they are
* injected into.
* injected into.</p>
*
* The newly created instance's [PostConstruct]-annotated methods will also have run already.
* <p>The newly created instance's [PostConstruct]-annotated methods will also have run already.</p>
*
* This event is only dispatched when there are one or more relevant listeners
* attached to the dispatching injector.
* <p>This event is only dispatched when there are one or more relevant listeners attached to
* the dispatching injector.</p>
*
* @eventType org.swiftsuspenders.InjectionEvent
* @eventType org.swiftsuspenders.InjectionEvent.POST_CONSTRUCT
*/
[Event(name='postConstruct', type='org.swiftsuspenders.InjectionEvent')]

/**
* This event is dispatched each time the injector creates a new mapping for a type/ name
* combination, right before the mapping is created
*
* At the point where the event is dispatched the mapping hasn't yet been created. Thus, the
* respective field in the event is null.
* <p>At the point where the event is dispatched the mapping hasn't yet been created. Thus, the
* respective field in the event is null.</p>
*
* This event is only dispatched when there are one or more relevant listeners
* attached to the dispatching injector.
* <p>This event is only dispatched when there are one or more relevant listeners attached to
* the dispatching injector.</p>
*
* @eventType org.swiftsuspenders.MappingEvent
* @eventType org.swiftsuspenders.MappingEvent.PRE_MAPPING_CREATE
*/
[Event(name='preMappingCreate', type='org.swiftsuspenders.MappingEvent')]
/**
* This event is dispatched each time the injector creates a new mapping for a type/ name
* combination, right after the mapping was created
*
* At the point where the event is dispatched the mapping has already been created and stored
* in the injector's lookup table.
* <p>At the point where the event is dispatched the mapping has already been created and stored
* in the injector's lookup table.</p>
*
* This event is only dispatched when there are one or more relevant listeners
* attached to the dispatching injector.
* <p>This event is only dispatched when there are one or more relevant listeners attached to
* the dispatching injector.</p>
*
* @eventType org.swiftsuspenders.MappingEvent
* @eventType org.swiftsuspenders.MappingEvent.POST_MAPPING_CREATE
*/
[Event(name='postMappingCreate', type='org.swiftsuspenders.MappingEvent')]
/**
* This event is dispatched each time an injector mapping is changed in any way, right before
* the change is applied.
*
* At the point where the event is dispatched the changes haven't yet been applied, meaning the
* mapping stored in the event can be queried for its pre-change state
* <p>At the point where the event is dispatched the changes haven't yet been applied, meaning the
* mapping stored in the event can be queried for its pre-change state.</p>
*
* This event is only dispatched when there are one or more relevant listeners
* attached to the dispatching injector.
* <p>This event is only dispatched when there are one or more relevant listeners attached to
* the dispatching injector.</p>
*
* @eventType org.swiftsuspenders.MappingEvent
* @eventType org.swiftsuspenders.MappingEvent.PRE_MAPPING_CHANGE
*/
[Event(name='preMappingChange', type='org.swiftsuspenders.MappingEvent')]
/**
* This event is dispatched each time an injector mapping is changed in any way, right after
* the change is applied.
*
* At the point where the event is dispatched the changes have already been applied, meaning
* the mapping stored in the event can be queried for its post-change state
* <p>At the point where the event is dispatched the changes have already been applied, meaning
* the mapping stored in the event can be queried for its post-change state</p>
*
* This event is only dispatched when there are one or more relevant listeners
* attached to the dispatching injector.
* <p>This event is only dispatched when there are one or more relevant listeners attached to
* the dispatching injector.</p>
*
* @eventType org.swiftsuspenders.MappingEvent
* @eventType org.swiftsuspenders.MappingEvent.POST_MAPPING_CHANGE
*/
[Event(name='postMappingChange', type='org.swiftsuspenders.MappingEvent')]
/**
* This event is dispatched each time an injector mapping is removed, right after
* the mapping is deleted from the configuration.
*
* At the point where the event is dispatched the changes have already been applied, meaning
* the mapping is lost to the injector and can't be queried anymore
* <p>At the point where the event is dispatched the changes have already been applied, meaning
* the mapping is lost to the injector and can't be queried anymore.</p>
*
* This event is only dispatched when there are one or more relevant listeners
* attached to the dispatching injector.
* <p>This event is only dispatched when there are one or more relevant listeners attached to
* the dispatching injector.</p>
*
* @eventType org.swiftsuspenders.MappingEvent
* @eventType org.swiftsuspenders.MappingEvent.POST_MAPPING_REMOVE
*/
[Event(name='postMappingRemove', type='org.swiftsuspenders.MappingEvent')]


/**
* The <code>Injector</code> manages the mappings and acts as the central hub from which all
* injections are started.
*/
public class Injector extends EventDispatcher
{
//---------------------- Private / Protected Properties ----------------------//
Expand All @@ -164,12 +167,42 @@ package org.swiftsuspenders
_applicationDomain = ApplicationDomain.currentDomain;
}

/**
* Maps a request description, consisting of the <code>type</code> and, optionally, the
* <code>name</code>.
*
* <p>The returned mapping is created if it didn't exist yet or simply returned otherwise.</p>
*
* <p>Named mappings should be used as sparingly as possible as they increase the likelyhood
* of typing errors to cause hard to debug errors at runtime.</p>
*
* @param type The <code>class</code> describing the mapping
* @param name The name, as a case-sensitive string, to further describe the mapping
*
* @return The <code>InjectionMapping</code> for the given request description
*
* @see #unmap()
* @see InjectionMapping
*/
public function map(type : Class, name : String = '') : InjectionMapping
{
const mappingId : String = getQualifiedClassName(type) + '|' + name;
return _mappings[mappingId] || createMapping(type, name, mappingId);
}

/**
* Removes the mapping described by the given <code>type</code> and <code>name</code>.
*
* @param type The <code>class</code> describing the mapping
* @param name The name, as a case-sensitive string, to further describe the mapping
*
* @throws org.swiftsuspenders.InjectorError Descriptions that are not mapped can't be unmapped
* @throws org.swiftsuspenders.InjectorError Sealed mappings have to be unsealed before unmapping them
*
* @see #map()
* @see InjectionMapping
* @see InjectionMapping#unseal()
*/
public function unmap(type : Class, name : String = '') : void
{
const mappingId : String = getQualifiedClassName(type) + '|' + name;
Expand All @@ -194,6 +227,7 @@ package org.swiftsuspenders
* by using a mapping of its own or by querying one of its ancestor injectors.
*
* @param type The dependency under query
*
* @return <code>true</code> if the dependency can be satisfied, <code>false</code> if not
*/
public function satisfies(type : Class, name : String = '') : Boolean
Expand All @@ -203,12 +237,13 @@ package org.swiftsuspenders

/**
* Indicates whether the injector can directly supply a response for the specified
* dependency
* dependency.
*
* In contrast to <code>satisfies</code>, <code>satisfiesDirectly</code> only informs
* about mappings on this injector itself, without querying its ancestor injectors.
* <p>In contrast to <code>#satisfies()</code>, <code>satisfiesDirectly</code> only informs
* about mappings on this injector itself, without querying its ancestor injectors.</p>
*
* @param type The dependency under query
*
* @return <code>true</code> if the dependency can be satisfied, <code>false</code> if not
*/
public function satisfiesDirectly(type : Class, name : String = '') : Boolean
Expand All @@ -219,15 +254,17 @@ package org.swiftsuspenders
/**
* Returns the mapping for the specified dependency class
*
* Note that getMapping will only return mappings in exactly this injector, not ones
* <p>Note that getMapping will only return mappings in exactly this injector, not ones
* mapped in an ancestor injector. To get mappings from ancestor injectors, query them
* using <code>parentInjector</code>.
* This restriction is in place to prevent accidential changing of mappings in ancestor
* injectors where only the child's response is meant to be altered.
* injectors where only the child's response is meant to be altered.</p>
*
* @param type The dependency to return the mapping for
*
* @return The mapping for the specified dependency class
* @throws InjectorError when no mapping was found for the specified dependency
*
* @throws InjectorError When no mapping was found for the specified dependency
*/
public function getMapping(type : Class, name : String = '') : InjectionMapping
{
Expand All @@ -241,6 +278,15 @@ package org.swiftsuspenders
return mapping;
}

/**
* Inspects the given object and injects into all injection points configured for its class.
*
* @param target The instance to inject into
*
* @throws org.swiftsuspenders.InjectorError The <code>Injector</code> must have mappings for all injection points
*
* @see #map()
*/
public function injectInto(target : Object) : void
{
const type : Class = getConstructor(target);
Expand All @@ -249,6 +295,17 @@ package org.swiftsuspenders
applyInjectionPoints(target, type, ctorInjectionPoint.next);
}

/**
* Instantiates the class identified by the given <code>type</code> and <code>name</code>.
*
* <p>If no <code>InjectionMapping</code> is found for the given <code>type</code> and no
* <code>name</code> is given, the class is simply instantiated and then injected into.</p>
*
* @param type The <code>class</code> describing the mapping
* @param name The name, as a case-sensitive string, to further describe the mapping
*
* @return The created instance
*/
public function getInstance(type : Class, name : String = '') : *
{
const mappingId : String = getQualifiedClassName(type) + '|' + name;
Expand All @@ -264,19 +321,44 @@ package org.swiftsuspenders
}
return instantiateUnmapped(type, type);
}


/**
* Creates a new <code>Injector</code> and sets itself as that new <code>Injector</code>'s
* <code>parentInjector</code>.
*
* @param applicationDomain The optional domain to use in the new Injector.
* If not given, the creating injector's domain is set on the new Injector as well.
* @return The newly created <code>Injector</code> instance
*
* @see #parentInjector
*/
public function createChildInjector(applicationDomain : ApplicationDomain = null) : Injector
{
var injector : Injector = new Injector();
injector.applicationDomain = applicationDomain;
injector.applicationDomain = applicationDomain || this.applicationDomain;
injector.parentInjector = this;
return injector;
}

/**
* Sets the <code>Injector</code> to ask in case the current <code>Injector</code> doesn't
* have a mapping for a dependency.
*
* <p>Parent Injectors can be nested in arbitrary depths with very little overhead,
* enabling very modular setups for the managed object graphs.</p>
*
* @param parentInjector The <code>Injector</code> to use for dependencies the current
* <code>Injector</code> can't supply
*/
public function set parentInjector(parentInjector : Injector) : void
{
_parentInjector = parentInjector;
}

/**
* Returns the <code>Injector</code> used for dependencies the current
* <code>Injector</code> can't supply
*/
public function get parentInjector() : Injector
{
return _parentInjector;
Expand Down
3 changes: 0 additions & 3 deletions src/org/swiftsuspenders/MappingEvent.as
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,6 @@ package org.swiftsuspenders
* @eventType preMappingChange
*/
public static const PRE_MAPPING_CHANGE : String = 'preMappingChange';
/**
* @eventType postMappingChange
*/
/**
* @eventType postMappingChange
*/
Expand Down

0 comments on commit 21051a0

Please sign in to comment.