SpongePowered/SpongeAPI — pull request #325 by ST-DDT (2014-12-26 19:35:10+00:00)
Title: Extended PermissionAPI

Extended Permission API.
This is a concept not a ready to pull PR.

The currently implemented permission API lacks a way to register new permissions with their default values and provide a description attached to them.

**Things added**
- SubjectData
- `getPermissionAuthority(permission)` - returns the subject that has granted/declined the permision
- `getPermissionValue(permission, Class)` - for Permissions that can hold other values that true or false, like Chat Prefixes
- `getPermissionValueAuthority(permission)`
- `SubjectGroup` (extends Subject, players can also be a subject group)
- `SubjectGroups`
- `DEFAULT`
- `OPERATOR`
- `MutableSubject` (Allow adding permissions to)
- `NamedSubject` (For `Subject`s that have a name, useful for groups or player names)
- PermissionService
- `registerPermission(permission, description)`
- `getRegisteredPermissions()`
- `getDescription(permission)`

**Additional information**
`Subject`is a permission holder
* so it can be a collection of permissions like Bukkit used for child permission
* it can be a player
* it can be a permission group like those used by most permission plugins
There is a global Context that is potentially valid on all worlds it may be ommited by plugins for specific worlds/times.
Users are normally valid on more than world so there is a view that can limit the check to a specific world/context (`ContextualizableSubject`) on the other hand groups are sometimes a valid on all worlds and sometimes only valid in a single world (`ContextualSubject`).
In same cases you don't want all context available for a short while (example while the user is inside an arena) so it is possible to enforce a single context for the user, so that you can limit the users abilities temporarly without messing with his permissions at all or just blocking his commands. The custom context's subject does also support parent groups and can also add some kind of fallback to the normal permissions outside the custom context.

Why i decided to add `SubjectGroup`s and especially `DEFAULT`, `OPERATOR`:
Currently there are 2-4 permission default values a permission can have: False, True, OP, NO-OP.
This assumes that vanilla minecraft itself has only two roles: Player and Owner
We all know that this kind of permission system is way to simple to be useful for servers that are used outside of your local network/friend list. So there is a chance that there will be added more roles. In this case the old 2-4 value system can no longer work properly, so i decided to skip it and use those groups to add the permissions to. If you want a permission only available for operators you use
````java
permissionService.registerPermission("plugin.XYZ.myadminPermission", someDescription);
SubjectGroups.DEFAULT.setPermission("plugin.XYZ.myadminPermission", false);
// SubjectGroups.SUPPORTER.setPermission("plugin.XYZ.myadminPermission", false);
SubjectGroups.OPERATOR.setPermission("plugin.XYZ.myadminPermission", true);
````
I register the declined permission just to be sure, because the `SUPPORTER` group may default to true internally.

Why i decided to add an (optional) value support.
Some permissions are very hard to encode using boolean permissions like how many homes a player can have or the well know chat prefix.

The names are not final, so if you have a better one propose it.
Another thought i had with the permission values is using the persistance api there, but ii is not yet finished yet so I use this simple alternative for now.