While Contexts create a bucket to hold your agents, Projections impose a structure upon those agents.  Simply using Contexts, you could never write a model that provided more than a simple "soup" for the agents.  The only way to grab other agents would be randomly.  Projections allow you to create a structure that defines relationships, whether they be spatial, network, or something else.  A projection os attached to a particular Context and applies to all of the agents in that Context.  This raises an important point.  An object must exist in a Context before it can be used in a projection.  So, if you try to work with an agent in a projection before you have added it to the Context, it will fail.  For example, if you have a network, and you try to create a link between agents where at least one of the agents does not yet exist in the context, then the operation will fail.  This is to maintain the integrity of the context which is used in many place throughout the repast system.

You can apply as many projections to a context as you want, so you could have a context that contains, a grid, a gis space and 4 networks if you felt so inclined.  This provides a great deal of flexibility to design your model. 

Your agents can get a reference to various projections through their enclosing context.  An agent could do the following where "this" refers to the agent:

Context context = ContextUtils.getContext (this)

Projection projection = context.getProjection("friendshipNetwork");

That projection wouldn't be that useful unless you cast the projection to something more specific.  You could also do it like this:

Context context = ContextUtils.getContext(this);

Network network = context.getProjection(Network.class, "friendshipNetwork");

That would take care of the casting for you.

Instantiating projections

In general, projections are created using a factory mechanism in the following way.

1. Find the factory
2. Use the factory to create the projection

 For example,

Context<SimpleHappyAgent> context = Contexts.createContext(SimpleHappyAgent.class, "my context");
NetworkFactory factory = NetworkFactoryFinder.createNetworkFactory(new HashMap());
Network network = factory.createNetwork("A Network", context, ...);

Context<SimpleHappyAgent> context = Contexts.createContext(SimpleHappyAgent.class, "my context"); 
GridFactory factory = GridFactoryFinder.createGridFactory(new HashMap());
Grid grid = factory.createGrid("Simple Grid", context, ...);

Context<SimpleHappyAgent> context = Contexts.createContext(SimpleHappyAgent.class, "my context"); 
ContinuousSpaceFactory factory = ContinuousSpaceFactoryFinder.createContinuousSpaceFactory(new HashMap());
ContinuousSpace space = factory.createContinuousSpace("Simple Space", context, ...);

Each factory creates a projection of a specific type and requires the context that the projection is associated with and the projections name as well as additional arguments particular to the projection type. These additional arguments are marked above with "..." and are explicated on the individual pages for that projection.