View source for Spaces/Authorization Support

Spaces has a convenience implementation of authorization support that space providers can use if there are no special needs.

The implementation is found in the project "org.eclipse.spaces.core", and there is a test in "org.eclipse.spaces.test" (class "SpaceAuthroizationTest").

=Storing Authorization Information=
Here is an example of how to store authorization information for a space.
<pre>
// A space URI
URI address = URI.create("spaces:local://user@localhost/MySpace1");

// Lookup the space
ISpace space = Spaces.getSpace(address);

// Create a space resource for the entire space
SpaceResource r = new SpaceResource(space);

// Add the authorization information
SpaceAuthorization.add(r,  new BasicCredentials("fred", "secret"));
</pre>
This adds information that user "fred" with password "secret" is authorization information for anything in the space (and below).

=Getting Authorization Information=
Here is an example how to obtain the authorization information:
<pre>
// A space URI
URI address = URI.create("spaces:local://user@localhost/MySpace1");

// Lookup the space
ISpace space = Spaces.getSpace(address);

// Create a space resource for the entire space
SpaceResource r = new SpaceResource(space);
BasicCredentials c = SpaceAuthorization.get(r, BasicCredentials.class);

String login = c.getLogin();
Stirng password = c.getPassword();
</pre>

=The SpaceResource=
The SpaceResource specifies the root of a resource tree. Here is the hierarchy
{| {{Greytable}} 	 
|- 	 
! Area
! Authorization for
! Example
|- valign="top"	 
| '''provider'''
| provider, server, user, space, and all three areas flat, structured, and source
| <code>new SpaceResource(space, SpaceResource.Type.PROVIDER)</code>
|- valign="top"	 
| '''server'''
| server, user, space, and all three areas flat, structured, and source
| <code>new SpaceResource(space, SpaceResource.Type.SERVER)</code>
|- valign="top"	 
| '''user'''
| user, space, and all three areas flat, structured, and source
| <code>new SpaceResource(space, SpaceResource.Type.USER)</code>
|- valign="top"	 
| '''space'''
| space, and all three areas flat, structured, and source
| <code>new SpaceResource(space)</code><br/> which is shorthand for:<br/><code>new SpaceResource(space, SpaceResource.Type.SPACE)</code>
|- valign="top"	 
| '''flat'''
| the flat area of a space
| <code>new SpaceResource(space, SpaceResource.Type.FLAT)</code>
|- valign="top"	 
| '''structure'''
| the structured area of a space
| <code>new SpaceResource(space, SpaceResource.Type.STRUCTURE)</code>
|- valign="top"	 
| '''source'''
| the source area of a space
| <code>new SpaceResource(space, SpaceResource.Type.SOURCE)</code>
|}

When a request is made to get authroization information for a space resource, the information added for the exact match, or the closest enclosing area's information is returned. 

This makes it possible to just add authroization information for the space, and still request information for flat, structure, and source individually. If no specific information has been defined for these areas, the information stored for the space will be returned.

The levels above space are useful when a user has one login/password for a larger group of spaces.
=Credentials=
The implementation contains support for BasicCredentials (login/password), but can be extended. If you want to add a new type of credential, extend the class from "org.eclipse.spaces.core.Credentials".
=Support for temporary Authorization=
The SpaceAuthroization class supports temporary authorizations (they are lost when the java runtime exits). The temporary authorization information has higher precedence when getting information. (This means that there could be information in the keyring for a space, and temporary information for the space's source repo - when looking up the source repo information, the temporary information is returned.

To add temporary information, simply use the "SpaceAuthorization.add(...)" with a signature that takes a boolean to control persistency.

=Example - headless use=
When using spaces headlessly, there are two options:
* Create a target platform that has credentials stored in the keyring and use this target platform when running.
* Pass credentials on the command line or read them from some file (up to how the headless commands work) and then either:
** store them in the keyring if this is wanted by the user
** store them in memory only (as shown above) - if the user prefers to pass credentials for every invocation