*****************************************************
Summary
-------
Generated at: 2012-11-20T17:27:31-06:00
Notes: 2
Binaries: 2
Archives: 0
Standards: 4

Apache Licensed: 2
Generated Documents: 0

JavaDocs are generated and so license header is optional
Generated files do not required license headers

2 Unknown Licenses

*******************************

Unapproved licenses:

  src/site/markdown/building.md
  src/site/markdown/index.md

*******************************

Archives:

*****************************************************
  Files with Apache License headers will be marked AL
  Binary files (which do not require AL headers) will be marked B
  Compressed archives will be marked A
  Notices, licenses etc will be marked N
  N     LICENSE.txt
  N     NOTICE.txt
  AL    pom.xml
 !????? src/site/markdown/building.md
 !????? src/site/markdown/index.md
  B     src/site/resources/images/privilizer-logo-white.png
  B     src/site/resources/images/privilizer-logo-white.xcf
  AL    src/site/site.xml
 
 *****************************************************
 Printing headers for files without AL header...
 
 
 =======================================================================
 ==src/site/markdown/building.md
 =======================================================================
Commons Privilizer is built using Maven 3 in typical fashion.  Things to know:

### Testing with security enabled
Since the whole point of the Privilizer relates to Java security, it is only
natural that its tests be executable with Java security enabled. It is also
reasonable to test without security enabled, to show that your code works as
always.  The `example` and `ant/test` modules each have a `sec` profile defined;
You can run their tests with this profile enabled to turn on Java security.

### Antlib Test module
Located at `ant/test`, this module\'s tests are implemented by unpacking the
source of the `example` module and reusing it.  For this reason, the
`example` module must have been packaged previously to executing the `ant/test`
tests, so in a multimodule build you should at least specify the `package`
phase of the default lifecycle.  Alternatively, you can disable this module\'s
tests by deactivating the profile in which they are set up: `antlib-test`.

Similarly, when building the project site you should deactivate the
`antlib-test` profile, to stop this module's tests from requiring the
`example` module to have been previously packaged. 

 =======================================================================
 ==src/site/markdown/index.md
 =======================================================================
# Commons Privilizer

Provides machinery to automate the handling of Java Security access
controls in code.  This involves wrapping calls that may trigger
`java.lang.SecurityException`s in `PrivilegedAction` objects.
Unfortunately this is quite an expensive operation and slows code
down considerably; when executed in an environment that has no
`SecurityManager` activated it is an utter waste.
The typical pattern to cope with this is:

```java
if (System.getSecurityManager() != null) {
  AccessController.doPrivileged(new PrivilegedAction<Void>() {
    public Void run() {
      doSomethingThatRequiresPermissions();
      return null;
    }
  });
} else {
  doSomethingThatRequiresPermissions();
}
```

This becomes tedious in short order.  The immediate response of a
typical developer:  relegate the repetitive code to a set of
utility methods.  In the case of Java security, however, this
approach is considered risky.  The purpose of the Privilizer, then,
is to instrument compiled methods originally annotated with our
`@Privileged` annotation.  This annotation is retained in the
classfiles, but not available at runtime, and there are no runtime
dependencies.

### With Privilizer

```java

@Privileged
private void doSomethingThatRequiresPermissions() {
  ...
}
```

Commons Privilizer provides both a Maven plugin and an Antlib for
weaving your compiled, annotated classes. You can control the weaving
behavior by parameterizing the Maven goals and Ant task with
the [Policy][policy] and [AccessLevel][accessLevel] `enum`s.

[policy]: apidocs/org/apache/commons/privilizer/weave/Privilizer.Policy.html
[accessLevel]: apidocs/org/apache/commons/privilizer/weave/AccessLevel.html