Polish Reference Documentation

Polish Reference Documentation

- Improve emphasis
- Fix formatting
- Update to Spring Framework 5
- Bom -> BOM

Fixes: gh-5695

[[introduction]]
== Introduction

[[what-is-acegi-security]]
=== What is Spring Security?
Spring Security provides comprehensive security services for Java EE-based enterprise software applications.
There is a particular emphasis on supporting projects built using The Spring Framework, which is the leading Java EE solution for enterprise software development.
If you're not using Spring for developing enterprise applications, we warmly encourage you to take a closer look at it.
Some familiarity with Spring - and in particular dependency injection principles - will help you get up to speed with Spring Security more easily.

People use Spring Security for many reasons, but most are drawn to the project after finding the security features of Java EE's Servlet Specification or EJB Specification lack the depth required for typical enterprise application scenarios.
Whilst mentioning these standards, it's important to recognise that they are not portable at a WAR or EAR level.
Therefore, if you switch server environments, it is typically a lot of work to reconfigure your application's security in the new target environment.
Using Spring Security overcomes these problems, and also brings you dozens of other useful, customisable security features.

As you probably know two major areas of application security are _authentication_ and _authorization_ (or _access-control_).
These are the two main areas that Spring Security targets.
"Authentication" is the process of establishing a principal is who they claim to be (a "principal" generally means a user, device or some other system which can perform an action in your application).
"Authorization" refers to the process of deciding whether a principal is allowed to perform an action within your application.
To arrive at the point where an authorization decision is needed, the identity of the principal has already been established by the authentication process.
These concepts are common, and not at all specific to Spring Security.

At an authentication level, Spring Security supports a wide range of authentication models.
Most of these authentication models are either provided by third parties, or are developed by relevant standards bodies such as the Internet Engineering Task Force.
In addition, Spring Security provides its own set of authentication features.
Specifically, Spring Security currently supports authentication integration with all of these technologies:

* HTTP BASIC authentication headers (an IETF RFC-based standard)

* HTTP Digest authentication headers (an IETF RFC-based standard)

* HTTP X.509 client certificate exchange (an IETF RFC-based standard)

* LDAP (a very common approach to cross-platform authentication needs, especially in large environments)

* Form-based authentication (for simple user interface needs)

* OpenID authentication

* Authentication based on pre-established request headers (such as Computer Associates Siteminder)

* Jasig Central Authentication Service (otherwise known as CAS, which is a popular open source single sign-on system)

* Transparent authentication context propagation for Remote Method Invocation (RMI) and HttpInvoker (a Spring remoting protocol)

* Automatic "remember-me" authentication (so you can tick a box to avoid re-authentication for a predetermined period of time)

* Anonymous authentication (allowing every unauthenticated call to automatically assume a particular security identity)

* Run-as authentication (which is useful if one call should proceed with a different security identity)

* Java Authentication and Authorization Service (JAAS)

* Java EE container authentication (so you can still use Container Managed Authentication if desired)

* Kerberos

* Java Open Source Single Sign-On (JOSSO) *

* OpenNMS Network Management Platform *

* AppFuse *

* AndroMDA *

* Mule ESB *

* Direct Web Request (DWR) *

* Grails *

* Tapestry *

* JTrac *

* Jasypt *

* Roller *

* Elastic Path *

* Atlassian Crowd *

* Your own authentication systems (see below)

(* Denotes provided by a third party)

Many independent software vendors (ISVs) adopt Spring Security because of this significant choice of flexible authentication models.
Doing so allows them to quickly integrate their solutions with whatever their end clients need, without undertaking a lot of engineering or requiring the client to change their environment.
If none of the above authentication mechanisms suit your needs, Spring Security is an open platform and it is quite simple to write your own authentication mechanism.
Many corporate users of Spring Security need to integrate with "legacy" systems that don't follow any particular security standards, and Spring Security is happy to "play nicely" with such systems.

Irrespective of the authentication mechanism, Spring Security provides a deep set of authorization capabilities.
There are three main areas of interest: authorizing web requests, authorizing whether methods can be invoked and authorizing access to individual domain object instances.
To help you understand the differences, consider the authorization capabilities found in the Servlet Specification web pattern security, EJB Container Managed Security and file system security respectively.
Spring Security provides deep capabilities in all of these important areas, which we'll explore later in this reference guide.

[[history]]
=== History
Spring Security began in late 2003 as "The Acegi Security System for Spring".
A question was posed on the Spring Developers' mailing list asking whether there had been any consideration given to a Spring-based security implementation.
At the time the Spring community was relatively small (especially compared with the size today!), and indeed Spring itself had only existed as a SourceForge project from early 2003.
The response to the question was that it was a worthwhile area, although a lack of time currently prevented its exploration.

With that in mind, a simple security implementation was built and not released.
A few weeks later another member of the Spring community inquired about security, and at the time this code was offered to them.
Several other requests followed, and by January 2004 around twenty people were using the code.
These pioneering users were joined by others who suggested a SourceForge project was in order, which was duly established in March 2004.

In those early days, the project didn't have any of its own authentication modules.
Container Managed Security was relied upon for the authentication process, with Acegi Security instead focusing on authorization.
This was suitable at first, but as more and more users requested additional container support, the fundamental limitation of container-specific authentication realm interfaces became clear.
There was also a related issue of adding new JARs to the container's classpath, which was a common source of end user confusion and misconfiguration.

Acegi Security-specific authentication services were subsequently introduced.
Around a year later, Acegi Security became an official Spring Framework subproject.
The 1.0.0 final release was published in May 2006 - after more than two and a half years of active use in numerous production software projects and many hundreds of improvements and community contributions.

Acegi Security became an official Spring Portfolio project towards the end of 2007 and was rebranded as _Spring Security_.

Today Spring Security enjoys a strong and active open source community.
There are thousands of messages about Spring Security on the support forums.
There is an active core of developers who work on the code itself and an active community which also regularly share patches and support their peers.

[[release-numbering]]
=== Release Numbering
It is useful to understand how Spring Security release numbers work, as it will help you identify the effort (or lack thereof) involved in migrating to future releases of the project.
Each release uses a standard triplet of integers: MAJOR.MINOR.PATCH.
The intent is that MAJOR versions are incompatible, large-scale upgrades of the API.
MINOR versions should largely retain source and binary compatibility with older minor versions, thought there may be some design changes and incompatible updates.
PATCH level should be perfectly compatible, forwards and backwards, with the possible exception of changes which are to fix bugs and defects.

The extent to which you are affected by changes will depend on how tightly integrated your code is.
If you are doing a lot of customization you are more likely to be affected than if you are using a simple namespace configuration.

You should always test your application thoroughly before rolling out a new version.

[[get-spring-security]]
=== Getting Spring Security
You can get hold of Spring Security in several ways.
You can download a packaged distribution from the main http://spring.
io/spring-security[Spring Security] page, download individual jars from the Maven Central repository (or a Spring Maven repository for snapshot and milestone releases) or, alternatively, you can build the project from source yourself.

[[maven]]
==== Usage with Maven

A minimal Spring Security Maven set of dependencies typically looks like the following:

.pom.xml
[source,xml]
[subs="verbatim,attributes"]
----
<dependencies>
<!-- ... other dependency elements ... -->
<dependency>
	<groupId>org.springframework.security</groupId>
	<artifactId>spring-security-web</artifactId>
	<version>{spring-security-version}</version>
</dependency>
<dependency>
	<groupId>org.springframework.security</groupId>
	<artifactId>spring-security-config</artifactId>
	<version>{spring-security-version}</version>
</dependency>
</dependencies>
----

If you are using additional features like LDAP, OpenID, etc. you will need to also include the appropriate <<modules>>.

[[maven-repositories]]
===== Maven Repositories
All GA releases (i.e. versions ending in .RELEASE) are deployed to Maven Central, so no additional Maven repositories need to be declared in your pom.

If you are using a SNAPSHOT version, you will need to ensure you have the Spring Snapshot repository defined as shown below:

.pom.xml
[source,xml]
----
<repositories>
<!-- ... possibly other repository elements ... -->
<repository>
	<id>spring-snapshot</id>
	<name>Spring Snapshot Repository</name>
	<url>http://repo.spring.io/snapshot</url>
</repository>
</repositories>
----

If you are using a milestone or release candidate version, you will need to ensure you have the Spring Milestone repository defined as shown below:

.pom.xml
[source,xml]
----
<repositories>
<!-- ... possibly other repository elements ... -->
<repository>
	<id>spring-milestone</id>
	<name>Spring Milestone Repository</name>
	<url>http://repo.spring.io/milestone</url>
</repository>
</repositories>
----

[[maven-bom]]
===== Spring Framework BOM

Spring Security builds against Spring Framework {spring-version}, but should work with 5
The problem that many users will have is that Spring Security's transitive dependencies resolve Spring Framework {spring-version} which can cause strange classpath problems.

One (tedious) way to circumvent this issue would be to include all the Spring Framework modules in a http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#Dependency_Management[<dependencyManagement>] section of your pom.
An alternative approach is to include the `spring-framework-bom` within your `<dependencyManagement>` section of your `pom.xml` as shown below:

.pom.xml
[source,xml]
[subs="verbatim,attributes"]
----
<dependencyManagement>
	<dependencies>
	<dependency>
		<groupId>org.springframework</groupId>
		<artifactId>spring-framework-bom</artifactId>
		<version>{spring-version}</version>
		<type>pom</type>
		<scope>import</scope>
	</dependency>
	</dependencies>
</dependencyManagement>
----

This will ensure that all the transitive dependencies of Spring Security use the Spring {spring-version} modules.

NOTE: This approach uses Maven's "bill of materials" (BOM) concept and is only available in Maven 2.0.9+.
For additional details about how dependencies are resolved refer to http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html[Maven's Introduction to the Dependency Mechanism documentation].

[[gradle]]
==== Gradle
A minimal Spring Security Gradle set of dependencies typically looks like the following:

.build.gradle
[source,groovy]
[subs="verbatim,attributes"]
----
dependencies {
	compile 'org.springframework.security:spring-security-web:{spring-security-version}'
	compile 'org.springframework.security:spring-security-config:{spring-security-version}'
}
----

If you are using additional features like LDAP, OpenID, etc. you will need to also include the appropriate <<modules>>.

[[gradle-repositories]]
===== Gradle Repositories
All GA releases (i.e. versions ending in .RELEASE) are deployed to Maven Central, so using the mavenCentral() repository is sufficient for GA releases.

.build.gradle
[source,groovy]
----
repositories {
	mavenCentral()
}
----

If you are using a SNAPSHOT version, you will need to ensure you have the Spring Snapshot repository defined as shown below:

.build.gradle
[source,groovy]
----
repositories {
	maven { url 'https://repo.spring.io/snapshot' }
}
----

If you are using a milestone or release candidate version, you will need to ensure you have the Spring Milestone repository defined as shown below:

.build.gradle
[source,groovy]
----
repositories {
	maven { url 'https://repo.spring.io/milestone' }
}
----

[[gradle-resolutionStrategy]]
===== Using Spring 4.0.x and Gradle

By default Gradle will use the newest version when resolving transitive versions.
This means that often times no additional work is necessary when running Spring Security {spring-security-version} with Spring Framework {spring-version}.
However, at times there can be issues that come up so it is best to mitigate this using http://www.gradle.org/docs/current/dsl/org.gradle.api.artifacts.ResolutionStrategy.html[Gradle's ResolutionStrategy] as shown below:

.build.gradle
[source,groovy]
[subs="verbatim,attributes"]
----
configurations.all {
	resolutionStrategy.eachDependency { DependencyResolveDetails details ->
		if (details.requested.group == 'org.springframework') {
			details.useVersion '{spring-version}'
		}
	}
}
----

This will ensure that all the transitive dependencies of Spring Security use the Spring {spring-version} modules.

NOTE: This example uses Gradle 1.9, but may need modifications to work in future versions of Gradle since this is an incubating feature within Gradle.

[[modules]]
==== Project Modules
In Spring Security 3.0, the codebase has been sub-divided into separate jars which more clearly separate different functionality areas and third-party dependencies.
If you are using Maven to build your project, then these are the modules you will add to your `pom.xml`.
Even if you're not using Maven, we'd recommend that you consult the `pom.xml` files to get an idea of third-party dependencies and versions.
Alternatively, a good idea is to examine the libraries that are included in the sample applications.

[[spring-security-core]]
===== Core - spring-security-core.jar
Contains core authentication and access-contol classes and interfaces, remoting support and basic provisioning APIs.
Required by any application which uses Spring Security.
Supports standalone applications, remote clients, method (service layer) security and JDBC user provisioning.
Contains the top-level packages:

* `org.springframework.security.core`

* `org.springframework.security.access`

* `org.springframework.security.authentication`

* `org.springframework.security.provisioning`

[[spring-security-remoting]]
===== Remoting - spring-security-remoting.jar
Provides intergration with Spring Remoting.
You don't need this unless you are writing a remote client which uses Spring Remoting.
The main package is `org.springframework.security.remoting`.

[[spring-security-web]]
===== Web - spring-security-web.jar
Contains filters and related web-security infrastructure code.
Anything with a servlet API dependency.
You'll need it if you require Spring Security web authentication services and URL-based access-control.
The main package is `org.springframework.security.web`.

[[spring-security-config]]
===== Config - spring-security-config.jar
Contains the security namespace parsing code & Java configuration code.
You need it if you are using the Spring Security XML namespace for configuration or Spring Security's Java Configuration support.
The main package is `org.springframework.security.config`.
None of the classes are intended for direct use in an application.

[[spring-security-ldap]]
===== LDAP - spring-security-ldap.jar
LDAP authentication and provisioning code.
Required if you need to use LDAP authentication or manage LDAP user entries.
The top-level package is `org.springframework.security.ldap`.

[[spring-security-oauth2-core]]
===== OAuth 2.0 Core - spring-security-oauth2-core.jar
`spring-security-oauth2-core.jar` contains core classes and interfaces that provide support for the _OAuth 2.0 Authorization Framework_ and for _OpenID Connect Core 1.0_.
It is required by applications that use _OAuth 2.0_ or _OpenID Connect Core 1.0_, such as Client, Resource Server, and Authorization Server.
The top-level package is `org.springframework.security.oauth2.core`.

[[spring-security-oauth2-client]]
===== OAuth 2.0 Client - spring-security-oauth2-client.jar
`spring-security-oauth2-client.jar` is Spring Security's client support for _OAuth 2.0 Authorization Framework_ and _OpenID Connect Core 1.0_.
Required by applications leveraging *OAuth 2.0 Login* and/or OAuth Client support.
The top-level package is `org.springframework.security.oauth2.client`.

[[spring-security-oauth2-jose]]
===== OAuth 2.0 JOSE - spring-security-oauth2-jose.jar
`spring-security-oauth2-jose.jar` contains Spring Security's support for the _JOSE_ (Javascript Object Signing and Encryption) framework.
The _JOSE_ framework is intended to provide a method to securely transfer claims between parties.
It is built from a collection of specifications:

* JSON Web Token (JWT)
* JSON Web Signature (JWS)
* JSON Web Encryption (JWE)
* JSON Web Key (JWK)

It contains the top-level packages:

* `org.springframework.security.oauth2.jwt`
* `org.springframework.security.oauth2.jose`

[[spring-security-acl]]
===== ACL - spring-security-acl.jar
Specialized domain object ACL implementation.
Used to apply security to specific domain object instances within your application.
The top-level package is `org.springframework.security.acls`.

[[spring-security-cas]]
===== CAS - spring-security-cas.jar
Spring Security's CAS client integration.
If you want to use Spring Security web authentication with a CAS single sign-on server.
The top-level package is `org.springframework.security.cas`.

[[spring-security-openid]]
===== OpenID - spring-security-openid.jar
OpenID web authentication support.
Used to authenticate users against an external OpenID server.
`org.springframework.security.openid`.
Requires OpenID4Java.

[[spring-security-test]]
===== Test - spring-security-test.jar
Support for testing with Spring Security.

[[get-source]]
==== Checking out the Source
Since Spring Security is an Open Source project, we'd strongly encourage you to check out the source code using git.
This will give you full access to all the sample applications and you can build the most up to date version of the project easily.
Having the source for a project is also a huge help in debugging.
Exception stack traces are no longer obscure black-box issues but you can get straight to the line that's causing the problem and work out what's happening.
The source is the ultimate documentation for a project and often the simplest place to find out how something actually works.

To obtain the source for the project, use the following git command:

[source,txt]
----
git clone https://github.com/spring-projects/spring-security.git
----

This will give you access to the entire project history (including all releases and branches) on your local machine.

[[introduction]]
== Introduction

[[what-is-acegi-security]]
=== What is Spring Security?
Spring Security provides comprehensive security services for Java EE-based enterprise software applications.
There is a particular emphasis on supporting projects built using The Spring Framework, which is the leading Java EE solution for enterprise software development.
If you're not using Spring for developing enterprise applications, we warmly encourage you to take a closer look at it.
Some familiarity with Spring - and in particular dependency injection principles - will help you get up to speed with Spring Security more easily.

People use Spring Security for many reasons, but most are drawn to the project after finding the security features of Java EE's Servlet Specification or EJB Specification lack the depth required for typical enterprise application scenarios.
Whilst mentioning these standards, it's important to recognise that they are not portable at a WAR or EAR level.
Therefore, if you switch server environments, it is typically a lot of work to reconfigure your application's security in the new target environment.
Using Spring Security overcomes these problems, and also brings you dozens of other useful, customisable security features.

As you probably know two major areas of application security are "authentication" and "authorization" (or "access-control").
These are the two main areas that Spring Security targets.
"Authentication" is the process of establishing a principal is who they claim to be (a "principal" generally means a user, device or some other system which can perform an action in your application).
"Authorization" refers to the process of deciding whether a principal is allowed to perform an action within your application.
To arrive at the point where an authorization decision is needed, the identity of the principal has already been established by the authentication process.
These concepts are common, and not at all specific to Spring Security.

At an authentication level, Spring Security supports a wide range of authentication models.
Most of these authentication models are either provided by third parties, or are developed by relevant standards bodies such as the Internet Engineering Task Force.
In addition, Spring Security provides its own set of authentication features.
Specifically, Spring Security currently supports authentication integration with all of these technologies:

* HTTP BASIC authentication headers (an IETF RFC-based standard)

* HTTP Digest authentication headers (an IETF RFC-based standard)

* HTTP X.509 client certificate exchange (an IETF RFC-based standard)

* LDAP (a very common approach to cross-platform authentication needs, especially in large environments)

* Form-based authentication (for simple user interface needs)

* OpenID authentication

* Authentication based on pre-established request headers (such as Computer Associates Siteminder)

* Jasig Central Authentication Service (otherwise known as CAS, which is a popular open source single sign-on system)

* Transparent authentication context propagation for Remote Method Invocation (RMI) and HttpInvoker (a Spring remoting protocol)

* Automatic "remember-me" authentication (so you can tick a box to avoid re-authentication for a predetermined period of time)

* Anonymous authentication (allowing every unauthenticated call to automatically assume a particular security identity)

* Run-as authentication (which is useful if one call should proceed with a different security identity)

* Java Authentication and Authorization Service (JAAS)

* Java EE container authentication (so you can still use Container Managed Authentication if desired)

* Kerberos

* Java Open Source Single Sign-On (JOSSO) *

* OpenNMS Network Management Platform *

* AppFuse *

* AndroMDA *

* Mule ESB *

* Direct Web Request (DWR) *

* Grails *

* Tapestry *

* JTrac *

* Jasypt *

* Roller *

* Elastic Path *

* Atlassian Crowd *

* Your own authentication systems (see below)

(* Denotes provided by a third party)

Many independent software vendors (ISVs) adopt Spring Security because of this significant choice of flexible authentication models.
Doing so allows them to quickly integrate their solutions with whatever their end clients need, without undertaking a lot of engineering or requiring the client to change their environment.
If none of the above authentication mechanisms suit your needs, Spring Security is an open platform and it is quite simple to write your own authentication mechanism.
Many corporate users of Spring Security need to integrate with "legacy" systems that don't follow any particular security standards, and Spring Security is happy to "play nicely" with such systems.

Irrespective of the authentication mechanism, Spring Security provides a deep set of authorization capabilities.
There are three main areas of interest: authorizing web requests, authorizing whether methods can be invoked and authorizing access to individual domain object instances.
To help you understand the differences, consider the authorization capabilities found in the Servlet Specification web pattern security, EJB Container Managed Security and file system security respectively.
Spring Security provides deep capabilities in all of these important areas, which we'll explore later in this reference guide.

[[history]]
=== History
Spring Security began in late 2003 as "The Acegi Security System for Spring".
A question was posed on the Spring Developers' mailing list asking whether there had been any consideration given to a Spring-based security implementation.
At the time the Spring community was relatively small (especially compared with the size today!), and indeed Spring itself had only existed as a SourceForge project from early 2003.
The response to the question was that it was a worthwhile area, although a lack of time currently prevented its exploration.

With that in mind, a simple security implementation was built and not released.
A few weeks later another member of the Spring community inquired about security, and at the time this code was offered to them.
Several other requests followed, and by January 2004 around twenty people were using the code.
These pioneering users were joined by others who suggested a SourceForge project was in order, which was duly established in March 2004.

In those early days, the project didn't have any of its own authentication modules.
Container Managed Security was relied upon for the authentication process, with Acegi Security instead focusing on authorization.
This was suitable at first, but as more and more users requested additional container support, the fundamental limitation of container-specific authentication realm interfaces became clear.
There was also a related issue of adding new JARs to the container's classpath, which was a common source of end user confusion and misconfiguration.

Acegi Security-specific authentication services were subsequently introduced.
Around a year later, Acegi Security became an official Spring Framework subproject.
The 1.
0.
0 final release was published in May 2006 - after more than two and a half years of active use in numerous production software projects and many hundreds of improvements and community contributions.

Acegi Security became an official Spring Portfolio project towards the end of 2007 and was rebranded as "Spring Security".

Today Spring Security enjoys a strong and active open source community.
There are thousands of messages about Spring Security on the support forums.
There is an active core of developers who work on the code itself and an active community which also regularly share patches and support their peers.

[[release-numbering]]
=== Release Numbering
It is useful to understand how Spring Security release numbers work, as it will help you identify the effort (or lack thereof) involved in migrating to future releases of the project.
Each release uses a standard triplet of integers: MAJOR.MINOR.PATCH.
The intent is that MAJOR versions are incompatible, large-scale upgrades of the API.
MINOR versions should largely retain source and binary compatibility with older minor versions, thought there may be some design changes and incompatible updates.
PATCH level should be perfectly compatible, forwards and backwards, with the possible exception of changes which are to fix bugs and defects.

The extent to which you are affected by changes will depend on how tightly integrated your code is.
If you are doing a lot of customization you are more likely to be affected than if you are using a simple namespace configuration.

You should always test your application thoroughly before rolling out a new version.

[[get-spring-security]]
=== Getting Spring Security
You can get hold of Spring Security in several ways.
You can download a packaged distribution from the main http://spring.
io/spring-security[Spring Security] page, download individual jars from the Maven Central repository (or a Spring Maven repository for snapshot and milestone releases) or, alternatively, you can build the project from source yourself.

[[maven]]
==== Usage with Maven

A minimal Spring Security Maven set of dependencies typically looks like the following:

.pom.xml
[source,xml]
[subs="verbatim,attributes"]
----
<dependencies>
<!-- ... other dependency elements ... -->
<dependency>
	<groupId>org.springframework.security</groupId>
	<artifactId>spring-security-web</artifactId>
	<version>{spring-security-version}</version>
</dependency>
<dependency>
	<groupId>org.springframework.security</groupId>
	<artifactId>spring-security-config</artifactId>
	<version>{spring-security-version}</version>
</dependency>
</dependencies>
----

If you are using additional features like LDAP, OpenID, etc. you will need to also include the appropriate <<modules>>.

[[maven-repositories]]
===== Maven Repositories
All GA releases (i.e. versions ending in .RELEASE) are deployed to Maven Central, so no additional Maven repositories need to be declared in your pom.

If you are using a SNAPSHOT version, you will need to ensure you have the Spring Snapshot repository defined as shown below:

.pom.xml
[source,xml]
----
<repositories>
<!-- ... possibly other repository elements ... -->
<repository>
	<id>spring-snapshot</id>
	<name>Spring Snapshot Repository</name>
	<url>http://repo.spring.io/snapshot</url>
</repository>
</repositories>
----

If you are using a milestone or release candidate version, you will need to ensure you have the Spring Milestone repository defined as shown below:

.pom.xml
[source,xml]
----
<repositories>
<!-- ... possibly other repository elements ... -->
<repository>
	<id>spring-milestone</id>
	<name>Spring Milestone Repository</name>
	<url>http://repo.spring.io/milestone</url>
</repository>
</repositories>
----

[[maven-bom]]
===== Spring Framework Bom

Spring Security builds against Spring Framework {spring-version}, but should work with 4.0.x.
The problem that many users will have is that Spring Security's transitive dependencies resolve Spring Framework {spring-version} which can cause strange classpath problems.

One (tedious) way to circumvent this issue would be to include all the Spring Framework modules in a http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#Dependency_Management[<dependencyManagement>] section of your pom.
An alternative approach is to include the `spring-framework-bom` within your `<dependencyManagement>` section of your `pom.xml` as shown below:

.pom.xml
[source,xml]
[subs="verbatim,attributes"]
----
<dependencyManagement>
	<dependencies>
	<dependency>
		<groupId>org.springframework</groupId>
		<artifactId>spring-framework-bom</artifactId>
		<version>{spring-version}</version>
		<type>pom</type>
		<scope>import</scope>
	</dependency>
	</dependencies>
</dependencyManagement>
----

This will ensure that all the transitive dependencies of Spring Security use the Spring {spring-version} modules.

NOTE: This approach uses Maven's "bill of materials" (BOM) concept and is only available in Maven 2.0.9+.
For additional details about how dependencies are resolved refer to http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html[Maven's Introduction to the Dependency Mechanism documentation].

[[gradle]]
==== Gradle
A minimal Spring Security Gradle set of dependencies typically looks like the following:

.build.gradle
[source,groovy]
[subs="verbatim,attributes"]
----
dependencies {
	compile 'org.springframework.security:spring-security-web:{spring-security-version}'
	compile 'org.springframework.security:spring-security-config:{spring-security-version}'
}
----

If you are using additional features like LDAP, OpenID, etc. you will need to also include the appropriate <<modules>>.

[[gradle-repositories]]
===== Gradle Repositories
All GA releases (i.e. versions ending in .RELEASE) are deployed to Maven Central, so using the mavenCentral() repository is sufficient for GA releases.

.build.gradle
[source,groovy]
----
repositories {
	mavenCentral()
}
----

If you are using a SNAPSHOT version, you will need to ensure you have the Spring Snapshot repository defined as shown below:

.build.gradle
[source,groovy]
----
repositories {
	maven { url 'https://repo.spring.io/snapshot' }
}
----

If you are using a milestone or release candidate version, you will need to ensure you have the Spring Milestone repository defined as shown below:

.build.gradle
[source,groovy]
----
repositories {
	maven { url 'https://repo.spring.io/milestone' }
}
----

[[gradle-resolutionStrategy]]
===== Using Spring 4.0.x and Gradle

By default Gradle will use the newest version when resolving transitive versions.
This means that often times no additional work is necessary when running Spring Security {spring-security-version} with Spring Framework {spring-version}.
However, at times there can be issues that come up so it is best to mitigate this using http://www.gradle.org/docs/current/dsl/org.gradle.api.artifacts.ResolutionStrategy.html[Gradle's ResolutionStrategy] as shown below:

.build.gradle
[source,groovy]
[subs="verbatim,attributes"]
----
configurations.all {
	resolutionStrategy.eachDependency { DependencyResolveDetails details ->
		if (details.requested.group == 'org.springframework') {
			details.useVersion '{spring-version}'
		}
	}
}
----

This will ensure that all the transitive dependencies of Spring Security use the Spring {spring-version} modules.

NOTE: This example uses Gradle 1.9, but may need modifications to work in future versions of Gradle since this is an incubating feature within Gradle.

[[modules]]
==== Project Modules
In Spring Security 3.0, the codebase has been sub-divided into separate jars which more clearly separate different functionality areas and third-party dependencies.
If you are using Maven to build your project, then these are the modules you will add to your `pom.xml`.
Even if you're not using Maven, we'd recommend that you consult the `pom.xml` files to get an idea of third-party dependencies and versions.
Alternatively, a good idea is to examine the libraries that are included in the sample applications.

[[spring-security-core]]
===== Core - spring-security-core.jar
Contains core authentication and access-contol classes and interfaces, remoting support and basic provisioning APIs.
Required by any application which uses Spring Security.
Supports standalone applications, remote clients, method (service layer) security and JDBC user provisioning.
Contains the top-level packages:

* `org.springframework.security.core`

* `org.springframework.security.access`

* `org.springframework.security.authentication`

* `org.springframework.security.provisioning`

[[spring-security-remoting]]
===== Remoting - spring-security-remoting.jar
Provides intergration with Spring Remoting.
You don't need this unless you are writing a remote client which uses Spring Remoting.
The main package is `org.springframework.security.remoting`.

[[spring-security-web]]
===== Web - spring-security-web.jar
Contains filters and related web-security infrastructure code.
Anything with a servlet API dependency.
You'll need it if you require Spring Security web authentication services and URL-based access-control.
The main package is `org.springframework.security.web`.

[[spring-security-config]]
===== Config - spring-security-config.jar
Contains the security namespace parsing code & Java configuration code.
You need it if you are using the Spring Security XML namespace for configuration or Spring Security's Java Configuration support.
The main package is `org.springframework.security.config`.
None of the classes are intended for direct use in an application.

[[spring-security-ldap]]
===== LDAP - spring-security-ldap.jar
LDAP authentication and provisioning code.
Required if you need to use LDAP authentication or manage LDAP user entries.
The top-level package is `org.springframework.security.ldap`.

[[spring-security-oauth2-core]]
===== OAuth 2.0 Core - spring-security-oauth2-core.jar
`spring-security-oauth2-core.jar` contains core classes and interfaces that provide support for the _OAuth 2.0 Authorization Framework_ and for _OpenID Connect Core 1.0_.
It is required by applications that use _OAuth 2.0_ or _OpenID Connect Core 1.0_, such as Client, Resource Server, and Authorization Server.
The top-level package is `org.springframework.security.oauth2.core`.

[[spring-security-oauth2-client]]
===== OAuth 2.0 Client - spring-security-oauth2-client.jar
`spring-security-oauth2-client.jar` is Spring Security's client support for _OAuth 2.0 Authorization Framework_ and _OpenID Connect Core 1.0_.
Required by applications leveraging *OAuth 2.0 Login* and/or OAuth Client support.
The top-level package is `org.springframework.security.oauth2.client`.

[[spring-security-oauth2-jose]]
===== OAuth 2.0 JOSE - spring-security-oauth2-jose.jar
`spring-security-oauth2-jose.jar` contains Spring Security's support for the _JOSE_ (Javascript Object Signing and Encryption) framework.
The _JOSE_ framework is intended to provide a method to securely transfer claims between parties.
It is built from a collection of specifications:

* JSON Web Token (JWT)
* JSON Web Signature (JWS)
* JSON Web Encryption (JWE)
* JSON Web Key (JWK)

It contains the top-level packages:

* `org.springframework.security.oauth2.jwt`
* `org.springframework.security.oauth2.jose`

[[spring-security-acl]]
===== ACL - spring-security-acl.jar
Specialized domain object ACL implementation.
Used to apply security to specific domain object instances within your application.
The top-level package is `org.springframework.security.acls`.

[[spring-security-cas]]
===== CAS - spring-security-cas.jar
Spring Security's CAS client integration.
If you want to use Spring Security web authentication with a CAS single sign-on server.
The top-level package is `org.springframework.security.cas`.

[[spring-security-openid]]
===== OpenID - spring-security-openid.jar
OpenID web authentication support.
Used to authenticate users against an external OpenID server.
`org.springframework.security.openid`.
Requires OpenID4Java.

[[spring-security-test]]
===== Test - spring-security-test.jar
Support for testing with Spring Security.

[[get-source]]
==== Checking out the Source
Since Spring Security is an Open Source project, we'd strongly encourage you to check out the source code using git.
This will give you full access to all the sample applications and you can build the most up to date version of the project easily.
Having the source for a project is also a huge help in debugging.
Exception stack traces are no longer obscure black-box issues but you can get straight to the line that's causing the problem and work out what's happening.
The source is the ultimate documentation for a project and often the simplest place to find out how something actually works.

To obtain the source for the project, use the following git command:

[source,txt]
----
git clone https://github.com/spring-projects/spring-security.git
----

This will give you access to the entire project history (including all releases and branches) on your local machine.


PR#660

= Changelog

== 4.3.1 or higher - upcoming

* Make manifest merging less verbose
** See https://github.com/simpligility/android-maven-plugin/pull/650
** contributed by Nathan Toone https://github.com/Toonetown
* Fix building with debug mode and raw file directories
** See https://github.com/simpligility/android-maven-plugin/pull/649
** contributed by Nathan Toone https://github.com/Toonetown
* Fix continuous integration(use Travis Android support and enable/update ITs)
** See https://github.com/simpligility/android-maven-plugin/pull/641
** contributed by Csaba Kozák https://github.com/WonderCsabo
* Fix issue in which dudplicate files were added to the APK
** https://github.com/simpligility/android-maven-plugin/pull/661
** contributed by Andrew Bowley https://github.com/andrew-bowley

Planned changes:

* migrate more tests to be instrumentation tests with example projects
** see https://github.com/simpligility/android-maven-plugin/issues/452
* anything else contributed by the community

== 4.3.0 - released 2015-06-15

https://groups.google.com/d/msg/maven-android-developers/FB4mP5s1kvA/EFxbrnnbca0J[Release Announcement Post]

* Fixed processing of duplicate resources from dependencies
** See https://github.com/simpligility/android-maven-plugin/pull/614
** contributed by Marek Kedzierski https://github.com/kedzie
* Ability to choose the build tools version
** See https://github.com/simpligility/android-maven-plugin/pull/637
** Contributed by Benoit Billington https://github.com/Shusshu
* Added x86_64 and mips64 architectures to NDK support
** see https://github.com/simpligility/android-maven-plugin/pull/634
** Contributed by Marek Kedzierski http://kedzie.github.io/
* Migrated rest of the Google Code project content into site content
** Contributed by Manfred Moser http://www.simpligility.com
* Plugin updates
** Contributed by Manfred Moser http://www.simpligility.com

== 4.2.1 - released 2015-05-07

https://groups.google.com/d/msg/maven-android-developers/HOIC3b7MmoA/Z8XUXpsmT-EJ[Release Announcement Post]

* Refactored code base to com.simpligility to follow groupId
** Contributed by Manfred Moser http://www.simpligility.com
* Fixed NPE for undefined versionNamingPattern in ManifestMojo
** See https://github.com/simpligility/android-maven-plugin/pull/622
** Contributed by Leonid https://github.com/greek1979
* Fixed Error generating BuildConfig (ZipException: zip file is empty) if one of the dependent AARs has an empty classes.zip
** See https://github.com/simpligility/android-maven-plugin/issues/626
** Contributed by William Ferguson https://github.com/william-ferguson-au
* Updated Android SDK libraries 1.2.2 / 24.2.2
** contributed by Benoit Billington https://github.com/Shusshu
** contributed by Manfred Moser http://www.simpligility.com
* Support for Junit4 Test Runner based tests
** Usage requires deployment of Android SDK supplied Maven repositories to the
  local repository e.g. with Maven Android SDK Deployer
** see https://github.com/simpligility/android-maven-plugin/pull/625
** fixes https://github.com/simpligility/android-maven-plugin/issues/623
** fixes https://github.com/simpligility/android-maven-plugin/issues/617
** contributed by Hoyt Summers Pittman https://github.com/secondsun

== 4.2.0 - released 2015-04-15

https://groups.google.com/d/msg/maven-android-developers/-HhJutxX0u8/PAKA2dYDK2wJ[Release Announcement Post]

* Include internal jars from aar libraries by default
** see https://github.com/simpligility/android-maven-plugin/pull/586#issuecomment-74931486
* Don't include internal libs from transitive AAR deps into an AAR
** See https://github.com/simpligility/android-maven-plugin/pull/589
** contributed by Philip Schiffer https://github.com/hameno
* Better doco for destinationAndroidManifest parameter
** see https://github.com/simpligility/android-maven-plugin/pull/594
** contributed by Matthias Stevens https://github.com/mstevens83
* Project META-INF artifacts are included in APK
** see https://github.com/simpligility/android-maven-plugin/pull/602
** Contributed by Marek Marek Kedzierski https://github.com/kedzie
* Support for specifying debug port - automatically forward JDWP connection
** see https://github.com/simpligility/android-maven-plugin/pull/584
** and follow up commits
** contributed by Jaroslav Tulach https://github.com/jtulach
** and Manfred Moser http://www.simpligility.com
* Configurable encoding for publish mojo listing files
** see https://github.com/simpligility/android-maven-plugin/pull/603
** fixes https://github.com/simpligility/android-maven-plugin/issues/601
** contributed by Csaba Kozák https://github.com/WonderCsabo
* Checkstyle - removed deprecated check
** see https://github.com/simpligility/android-maven-plugin/issues/609
** contributed by Manfred Moser http://www.simpligility.com
* Add NDK support for arm64-v8a APP_ABI
** see https://github.com/simpligility/android-maven-plugin/pull/574
** contributed by https://github.com/arnaud-soulard
* Log warning about using dependencies conflicting with packaged libraries in android jar
** see https://github.com/simpligility/android-maven-plugin/pull/610
** contributed by Csaba Kozák https://github.com/WonderCsabo
* Allow AAR provided proguard configuration to be automatically integrated
** see https://github.com/simpligility/android-maven-plugin/pull/612
** contributed by Philip Schiffer https://github.com/hameno
* Updated Android SDK libraries 1.1.3 / 24.1.3
** see https://github.com/simpligility/android-maven-plugin/commit/60ec75aa8ab889c7033fd403149973c0d3b66f82
** see https://github.com/simpligility/android-maven-plugin/commit/869578d84af1f215bca341191bb0078899e3330c
** contributed by Manfred Moser http://www.simpligility.com
** contributed by Benoit Billington https://github.com/Shusshu
* Regex support for VersionGenerator
** fixes https://github.com/simpligility/android-maven-plugin/issues/605
** see https://github.com/simpligility/android-maven-plugin/pull/606
** contributed by Wang Xuerui https://github.com/xen0n

== 4.1.1 or higher - released 2015-02-02

https://groups.google.com/d/msg/maven-android-developers/EXYhXO1hbwM/L2mS3Ho7-kQJ[Release Announcement Post]

* Added Manifest Merger v2 example (tictactoe) & Deprecated merge manifest v1
** see https://github.com/simpligility/android-maven-plugin/pull/560
** contributed by Benoit Billington https://github.com/Shusshu
* Added proguard support from library (AAR) projects
** see https://github.com/simpligility/android-maven-plugin/pull/559
** contributed by David Sobreira Marques https://github.com/dpsm
* Updated Takari lifecyle and integration testing setup to new releases
** see https://github.com/simpligility/android-maven-plugin/pull/564
** contributed by Manfred Moser http://www.simpligility.com
** and Igor Fedorenko https://github.com/ifedorenko
** sponsored by Takari http://takari.io/
* Fix to allow both release-plugin and IDEs to correctly consume AAR deps.
** See https://github.com/simpligility/android-maven-plugin/pull/565
** contributed by Hoyt Summers Pittman https://github.com/secondsun
* Change default value for aidlSourceDirectory to src/main/aidl
** fixes https://github.com/simpligility/android-maven-plugin/issues/555
** see https://github.com/simpligility/android-maven-plugin/pull/557
** contributed by Csaba Kozák https://github.com/WonderCsabo
* Documentation updates for the site rendering
** see https://github.com/simpligility/android-maven-plugin/pull/567
** and other commits
** contributed by Manfred Moser http://www.simpligility.com
* Corrected unpackedLibsFolder default value
** see https://github.com/simpligility/android-maven-plugin/pull/575
** contributed by Pappy Stanescu https://github.com/pa314159
* Improvement of versionCode generator
** see https://github.com/simpligility/android-maven-plugin/pull/570
** contributed by Pappy Stanescu https://github.com/pa314159

== 4.1.0 - released 2015-01-08

https://groups.google.com/d/msg/maven-android-developers/oNm46DqGi2Q/Gs3cQAQ018gJ[Release Announcement Post]

* Updated to Android SDK libraries 1.0.0 / 24.0.0
** see https://github.com/simpligility/android-maven-plugin/pull/531
** contributed by Benoit Billington https://github.com/Shusshu
* Use lint from Android SDK libraries rather than command line invocation
** see https://github.com/simpligility/android-maven-plugin/pull/528
** fixes https://github.com/simpligility/android-maven-plugin/issues/400
** fixes https://github.com/simpligility/android-maven-plugin/issues/357
** fixes https://github.com/simpligility/android-maven-plugin/issues/476
** contributed by Benoit Billington https://github.com/Shusshu
* Making unpacked-libs folder configurable
** See https://github.com/simpligility/android-maven-plugin/pull/538
** contributed by William Ferguson https://github.com/william-ferguson-au
* Added deprecation for APKLIB format
** see https://github.com/simpligility/android-maven-plugin/pull/543
* Use the Google Play Developer API to upload APKs and update the store listing
** see https://github.com/simpligility/android-maven-plugin/pull/534
** fixes https://github.com/simpligility/android-maven-plugin/issues/418
** contributed by Joris de Groot https://github.com/jdegroot
** contributed by Benoit Billington https://github.com/Shusshu
* Improvements to project site including github ribbon and more
** see https://github.com/simpligility/android-maven-plugin/pull/544
** contributed by Manfred Moser http://www.simpligility.com
* Added Manifest Merger V2 and deprecated Manifest-Update mojo
** see https://github.com/simpligility/android-maven-plugin/pull/539
** fixes https://github.com/simpligility/android-maven-plugin/issues/519
** contributed by Benoit Billington https://github.com/Shusshu
* Refactor the 3 parameters used for the androidManifest.xml into 2 params
** see https://github.com/simpligility/android-maven-plugin/pull/542
** see https://github.com/simpligility/android-maven-plugin/issues/508
** contributed by Benoit Billington https://github.com/Shusshu
* Fixed broken undeploy mojo AndroidManifest parsing
** see https://github.com/simpligility/android-maven-plugin/issues/550
** contributed by Manfred Moser http://www.simpligility.com
* MultiDex improvement - generating mainDexClasses when multiDex flag set to true and mainDexList is null
** see https://github.com/simpligility/android-maven-plugin/pull/526
** contributed by Piotr Soróbka https://github.com/psorobka
* A whole bunch minor project improvements and fixes
** see commit history
** contributed by Manfred Moser http://www.simpligility.com

ATTENTION:

* updatedManifestFile & sourceManifestFile parameters have been removed.
* use androidManifestFile and destinationManifestFile
** See https://github.com/simpligility/android-maven-plugin/pull/542

== 4.0.0 - released 2014-11-25

https://groups.google.com/d/msg/maven-android-developers/9ogkKf0Xr7Y/F9CKX6LV0uAJ[Release Announcement Post]

* Migrated some documentation from the old Google Code site
** contributed by Manfred Moser http://www.simpligility.com
* Fix for aar and jar dependency mix and related resolving
** see https://github.com/simpligility/android-maven-plugin/pull/493
** fixes https://github.com/simpligility/android-maven-plugin/issues/485
** contributed by Hoyt Summers Pittman https://github.com/secondsun
* Fixes to proguard and multidex related processing
** see https://github.com/simpligility/android-maven-plugin/pull/509
** fixes https://github.com/simpligility/android-maven-plugin/issues/507
** contributed by Łukasz Suski https://github.com/lsuski
* Documentation for shading commons-codec to allow usage of newer version
** see https://github.com/simpligility/android-maven-plugin/pull/498
** see https://github.com/simpligility/android-maven-plugin/issues/487#issuecomment-60956025
** contributed by Matthias Stevens https://github.com/mstevens83
* Custom exclude filter to ProGuardMojo
** see https://github.com/simpligility/android-maven-plugin/pull/497
** contributed by Csaba Kozák https://github.com/WonderCsabo
* Fixes to resource files in sample projects to allow builds to pass with new SDK
** see https://github.com/simpligility/android-maven-plugin/pull/514
** contributed by Manfred Moser http://www.simpligility.com
* Always honor dexArguments parameters
** fixes https://github.com/simpligility/android-maven-plugin/issues/517
** contributed by Manfred Moser http://www.simpligility.com
* Downgraded runtime requirements to Maven 3.0.4
** contributed by Manfred Moser http://www.simpligility.com
* Examples documentation
** contributed by Manfred Moser http://www.simpligility.com
* Moved Emma analysis to process-classes phase
** fixes https://github.com/simpligility/android-maven-plugin/issues/489
** see https://github.com/simpligility/android-maven-plugin/pull/515
** contributed by Dmitry Berezhnoy https://github.com/deadmoto

== 4.0.0-rc.3 - released 2014-10-28

https://groups.google.com/d/msg/maven-android-developers/9ogkKf0Xr7Y/F9CKX6LV0uAJ[Release Announcement Post]

* Migrated complete project to new git repo at https://github.com/simpligility/android-maven-plugin
** contributed by Manfred Moser http://www.simpligility.com
* Adapted codebase to new groupId "com.simpligility.maven.plugins
** contributed by Manfred Moser http://www.simpligility.com

== 4.0.0-rc.2 and older release notes

Can be found in link:changelog-old-3x.html[the migrated changelog] from the old project site.

= Changelog

== 4.3.1 or higher - upcoming

* Make manifest merging less verbose
** See https://github.com/simpligility/android-maven-plugin/pull/650
** contributed by Nathan Toone https://github.com/Toonetown
* Fix building with debug mode and raw file directories
** See https://github.com/simpligility/android-maven-plugin/pull/649
** contributed by Nathan Toone https://github.com/Toonetown
* Fix continuous integration(use Travis Android support and enable/update ITs)
** See https://github.com/simpligility/android-maven-plugin/pull/641
** contributed by Csaba Kozák https://github.com/WonderCsabo

Planned changes:

* migrate more tests to be instrumentation tests with example projects
** see https://github.com/simpligility/android-maven-plugin/issues/452
* anything else contributed by the community

== 4.3.0 - released 2015-06-15

https://groups.google.com/d/msg/maven-android-developers/FB4mP5s1kvA/EFxbrnnbca0J[Release Announcement Post]

* Fixed processing of duplicate resources from dependencies
** See https://github.com/simpligility/android-maven-plugin/pull/614
** contributed by Marek Kedzierski https://github.com/kedzie
* Ability to choose the build tools version
** See https://github.com/simpligility/android-maven-plugin/pull/637
** Contributed by Benoit Billington https://github.com/Shusshu
* Added x86_64 and mips64 architectures to NDK support
** see https://github.com/simpligility/android-maven-plugin/pull/634
** Contributed by Marek Kedzierski http://kedzie.github.io/
* Migrated rest of the Google Code project content into site content
** Contributed by Manfred Moser http://www.simpligility.com
* Plugin updates
** Contributed by Manfred Moser http://www.simpligility.com

== 4.2.1 - released 2015-05-07

https://groups.google.com/d/msg/maven-android-developers/HOIC3b7MmoA/Z8XUXpsmT-EJ[Release Announcement Post]

* Refactored code base to com.simpligility to follow groupId
** Contributed by Manfred Moser http://www.simpligility.com
* Fixed NPE for undefined versionNamingPattern in ManifestMojo
** See https://github.com/simpligility/android-maven-plugin/pull/622
** Contributed by Leonid https://github.com/greek1979
* Fixed Error generating BuildConfig (ZipException: zip file is empty) if one of the dependent AARs has an empty classes.zip
** See https://github.com/simpligility/android-maven-plugin/issues/626
** Contributed by William Ferguson https://github.com/william-ferguson-au
* Updated Android SDK libraries 1.2.2 / 24.2.2
** contributed by Benoit Billington https://github.com/Shusshu
** contributed by Manfred Moser http://www.simpligility.com
* Support for Junit4 Test Runner based tests
** Usage requires deployment of Android SDK supplied Maven repositories to the
  local repository e.g. with Maven Android SDK Deployer
** see https://github.com/simpligility/android-maven-plugin/pull/625
** fixes https://github.com/simpligility/android-maven-plugin/issues/623
** fixes https://github.com/simpligility/android-maven-plugin/issues/617
** contributed by Hoyt Summers Pittman https://github.com/secondsun

== 4.2.0 - released 2015-04-15

https://groups.google.com/d/msg/maven-android-developers/-HhJutxX0u8/PAKA2dYDK2wJ[Release Announcement Post]

* Include internal jars from aar libraries by default
** see https://github.com/simpligility/android-maven-plugin/pull/586#issuecomment-74931486
* Don't include internal libs from transitive AAR deps into an AAR
** See https://github.com/simpligility/android-maven-plugin/pull/589
** contributed by Philip Schiffer https://github.com/hameno
* Better doco for destinationAndroidManifest parameter
** see https://github.com/simpligility/android-maven-plugin/pull/594
** contributed by Matthias Stevens https://github.com/mstevens83
* Project META-INF artifacts are included in APK
** see https://github.com/simpligility/android-maven-plugin/pull/602
** Contributed by Marek Marek Kedzierski https://github.com/kedzie
* Support for specifying debug port - automatically forward JDWP connection
** see https://github.com/simpligility/android-maven-plugin/pull/584
** and follow up commits
** contributed by Jaroslav Tulach https://github.com/jtulach
** and Manfred Moser http://www.simpligility.com
* Configurable encoding for publish mojo listing files
** see https://github.com/simpligility/android-maven-plugin/pull/603
** fixes https://github.com/simpligility/android-maven-plugin/issues/601
** contributed by Csaba Kozák https://github.com/WonderCsabo
* Checkstyle - removed deprecated check
** see https://github.com/simpligility/android-maven-plugin/issues/609
** contributed by Manfred Moser http://www.simpligility.com
* Add NDK support for arm64-v8a APP_ABI
** see https://github.com/simpligility/android-maven-plugin/pull/574
** contributed by https://github.com/arnaud-soulard
* Log warning about using dependencies conflicting with packaged libraries in android jar
** see https://github.com/simpligility/android-maven-plugin/pull/610
** contributed by Csaba Kozák https://github.com/WonderCsabo
* Allow AAR provided proguard configuration to be automatically integrated
** see https://github.com/simpligility/android-maven-plugin/pull/612
** contributed by Philip Schiffer https://github.com/hameno
* Updated Android SDK libraries 1.1.3 / 24.1.3
** see https://github.com/simpligility/android-maven-plugin/commit/60ec75aa8ab889c7033fd403149973c0d3b66f82
** see https://github.com/simpligility/android-maven-plugin/commit/869578d84af1f215bca341191bb0078899e3330c
** contributed by Manfred Moser http://www.simpligility.com
** contributed by Benoit Billington https://github.com/Shusshu
* Regex support for VersionGenerator
** fixes https://github.com/simpligility/android-maven-plugin/issues/605
** see https://github.com/simpligility/android-maven-plugin/pull/606
** contributed by Wang Xuerui https://github.com/xen0n

== 4.1.1 or higher - released 2015-02-02

https://groups.google.com/d/msg/maven-android-developers/EXYhXO1hbwM/L2mS3Ho7-kQJ[Release Announcement Post]

* Added Manifest Merger v2 example (tictactoe) & Deprecated merge manifest v1
** see https://github.com/simpligility/android-maven-plugin/pull/560
** contributed by Benoit Billington https://github.com/Shusshu
* Added proguard support from library (AAR) projects
** see https://github.com/simpligility/android-maven-plugin/pull/559
** contributed by David Sobreira Marques https://github.com/dpsm
* Updated Takari lifecyle and integration testing setup to new releases
** see https://github.com/simpligility/android-maven-plugin/pull/564
** contributed by Manfred Moser http://www.simpligility.com
** and Igor Fedorenko https://github.com/ifedorenko
** sponsored by Takari http://takari.io/
* Fix to allow both release-plugin and IDEs to correctly consume AAR deps.
** See https://github.com/simpligility/android-maven-plugin/pull/565
** contributed by Hoyt Summers Pittman https://github.com/secondsun
* Change default value for aidlSourceDirectory to src/main/aidl
** fixes https://github.com/simpligility/android-maven-plugin/issues/555
** see https://github.com/simpligility/android-maven-plugin/pull/557
** contributed by Csaba Kozák https://github.com/WonderCsabo
* Documentation updates for the site rendering
** see https://github.com/simpligility/android-maven-plugin/pull/567
** and other commits
** contributed by Manfred Moser http://www.simpligility.com
* Corrected unpackedLibsFolder default value
** see https://github.com/simpligility/android-maven-plugin/pull/575
** contributed by Pappy Stanescu https://github.com/pa314159
* Improvement of versionCode generator
** see https://github.com/simpligility/android-maven-plugin/pull/570
** contributed by Pappy Stanescu https://github.com/pa314159

== 4.1.0 - released 2015-01-08

https://groups.google.com/d/msg/maven-android-developers/oNm46DqGi2Q/Gs3cQAQ018gJ[Release Announcement Post]

* Updated to Android SDK libraries 1.0.0 / 24.0.0
** see https://github.com/simpligility/android-maven-plugin/pull/531
** contributed by Benoit Billington https://github.com/Shusshu
* Use lint from Android SDK libraries rather than command line invocation
** see https://github.com/simpligility/android-maven-plugin/pull/528
** fixes https://github.com/simpligility/android-maven-plugin/issues/400
** fixes https://github.com/simpligility/android-maven-plugin/issues/357
** fixes https://github.com/simpligility/android-maven-plugin/issues/476
** contributed by Benoit Billington https://github.com/Shusshu
* Making unpacked-libs folder configurable
** See https://github.com/simpligility/android-maven-plugin/pull/538
** contributed by William Ferguson https://github.com/william-ferguson-au
* Added deprecation for APKLIB format
** see https://github.com/simpligility/android-maven-plugin/pull/543
* Use the Google Play Developer API to upload APKs and update the store listing
** see https://github.com/simpligility/android-maven-plugin/pull/534
** fixes https://github.com/simpligility/android-maven-plugin/issues/418
** contributed by Joris de Groot https://github.com/jdegroot
** contributed by Benoit Billington https://github.com/Shusshu
* Improvements to project site including github ribbon and more
** see https://github.com/simpligility/android-maven-plugin/pull/544
** contributed by Manfred Moser http://www.simpligility.com
* Added Manifest Merger V2 and deprecated Manifest-Update mojo
** see https://github.com/simpligility/android-maven-plugin/pull/539
** fixes https://github.com/simpligility/android-maven-plugin/issues/519
** contributed by Benoit Billington https://github.com/Shusshu
* Refactor the 3 parameters used for the androidManifest.xml into 2 params
** see https://github.com/simpligility/android-maven-plugin/pull/542
** see https://github.com/simpligility/android-maven-plugin/issues/508
** contributed by Benoit Billington https://github.com/Shusshu
* Fixed broken undeploy mojo AndroidManifest parsing
** see https://github.com/simpligility/android-maven-plugin/issues/550
** contributed by Manfred Moser http://www.simpligility.com
* MultiDex improvement - generating mainDexClasses when multiDex flag set to true and mainDexList is null
** see https://github.com/simpligility/android-maven-plugin/pull/526
** contributed by Piotr Soróbka https://github.com/psorobka
* A whole bunch minor project improvements and fixes
** see commit history
** contributed by Manfred Moser http://www.simpligility.com

ATTENTION:

* updatedManifestFile & sourceManifestFile parameters have been removed.
* use androidManifestFile and destinationManifestFile
** See https://github.com/simpligility/android-maven-plugin/pull/542

== 4.0.0 - released 2014-11-25

https://groups.google.com/d/msg/maven-android-developers/9ogkKf0Xr7Y/F9CKX6LV0uAJ[Release Announcement Post]

* Migrated some documentation from the old Google Code site
** contributed by Manfred Moser http://www.simpligility.com
* Fix for aar and jar dependency mix and related resolving
** see https://github.com/simpligility/android-maven-plugin/pull/493
** fixes https://github.com/simpligility/android-maven-plugin/issues/485
** contributed by Hoyt Summers Pittman https://github.com/secondsun
* Fixes to proguard and multidex related processing
** see https://github.com/simpligility/android-maven-plugin/pull/509
** fixes https://github.com/simpligility/android-maven-plugin/issues/507
** contributed by Łukasz Suski https://github.com/lsuski
* Documentation for shading commons-codec to allow usage of newer version
** see https://github.com/simpligility/android-maven-plugin/pull/498
** see https://github.com/simpligility/android-maven-plugin/issues/487#issuecomment-60956025
** contributed by Matthias Stevens https://github.com/mstevens83
* Custom exclude filter to ProGuardMojo
** see https://github.com/simpligility/android-maven-plugin/pull/497
** contributed by Csaba Kozák https://github.com/WonderCsabo
* Fixes to resource files in sample projects to allow builds to pass with new SDK
** see https://github.com/simpligility/android-maven-plugin/pull/514
** contributed by Manfred Moser http://www.simpligility.com
* Always honor dexArguments parameters
** fixes https://github.com/simpligility/android-maven-plugin/issues/517
** contributed by Manfred Moser http://www.simpligility.com
* Downgraded runtime requirements to Maven 3.0.4
** contributed by Manfred Moser http://www.simpligility.com
* Examples documentation
** contributed by Manfred Moser http://www.simpligility.com
* Moved Emma analysis to process-classes phase
** fixes https://github.com/simpligility/android-maven-plugin/issues/489
** see https://github.com/simpligility/android-maven-plugin/pull/515
** contributed by Dmitry Berezhnoy https://github.com/deadmoto

== 4.0.0-rc.3 - released 2014-10-28

https://groups.google.com/d/msg/maven-android-developers/9ogkKf0Xr7Y/F9CKX6LV0uAJ[Release Announcement Post]

* Migrated complete project to new git repo at https://github.com/simpligility/android-maven-plugin
** contributed by Manfred Moser http://www.simpligility.com
* Adapted codebase to new groupId "com.simpligility.maven.plugins
** contributed by Manfred Moser http://www.simpligility.com

== 4.0.0-rc.2 and older release notes

Can be found in link:changelog-old-3x.html[the migrated changelog] from the old project site.


archiveLocalStartup: Updated documentation.

There is no longer a complex configuration for the table of contents
of local archives. Therefore, this section has been removed, and other
parts have been adapted accordingly.

= Local Media Archive Startup project

This module has the purpose to start the local media archive in an OSGi
environment.

== Description

This module is analogous to the startup project for the union archive, but
it is responsible for the _local media archive_. The local media archive
scans a folder structure with media files and passes the extracted meta data
to a union archive which can either run on the same JVM or is accessed
remotely.

Access to the union archive is obtained through the _client application
context_ available to all LineDJ platform components: actor references for the
actors implementing the archive are simply obtained from the _media facade_.
That way the location of the union archive is transparent.

The local archive is implemented by the following actors:

.Actors implementing the local archive
[cols="1,3",options="header"]
|==============================
| Actor class | Description
| ArchiveGroupActor | An actor managing a group of local paths that need to be
parsed for meta data files. For each path, the actor creates the other actors
for managing the media files. It is also responsible for the coordination of
scan operations.
| PersistentMetaDataManagerActor | The actor responsible for persistent meta
data files. It takes care that meta data extracted from media files is stored
on the local file system and is loaded again when the local archive restarts.
| MetaDataManagerActor | Controls the extraction of meta data from single media
files and sends the results to the union archive.
| MediaManagerActor | Scans a specified folder structure for media files and
collects information about media available. This information is sent to the
union archive.
|==============================

== Configuration

The configuration of the local media archive is also read from the
configuration file of the LineDJ management application (analogous as the
configuration for the union media archive; if both components are deployed in
the same platform container, they actually use the same configuration file,
and also their configuration sections overlap). The settings are placed in a
section named _media_. Below is an example fragment with all supported
configuration options:

[source,xml]
----
<configuration>
    <media>
        <mediaArchive>
            <metaDataUpdateChunkSize>32</metaDataUpdateChunkSize>
            <metaDataMaxMessageSize>128</metaDataMaxMessageSize>
        </mediaArchive>
        <localArchives>
            <processorCount>1</processorCount>
            <readerTimeout>3600</readerTimeout>
            <readerCheckInterval>600</readerCheckInterval>
            <readerCheckInitialDelay>480</readerCheckInitialDelay>
            <downloadChunkSize>16384</downloadChunkSize>
            <infoSizeLimit>32768</infoSizeLimit>
            <includedExtensions>MP3</includedExtensions>
            <scan>
                <parseInfoTimeout>10</parseInfoTimeout>
                <mediaBufferSize>3</mediaBufferSize>
            </scan>
            <metaDataExtraction>
                <readChunkSize>32768</readChunkSize>
                <tagSizeLimit>4096</tagSizeLimit>
                <metaDataUpdateChunkSize>8</metaDataUpdateChunkSize>
                <metaDataMaxMessageSize>160</metaDataMaxMessageSize>
                <processingTimeout>60</processingTimeout>
            </metaDataExtraction>
            <metaDataPersistence>
                <chunkSize>4096</chunkSize>
                <parallelCount>2</parallelCount>
                <writeBlockSize>40</writeBlockSize>
            </metaDataPersistence>
            <localArchive>
                <rootPath>/data/music/archive/1and1/media</rootPath>
                <archiveName>1and1-${host}</archiveName>
                <metaDataPersistence>
                    <path>/data/music/archive/1and1/metadata</path>
                    <tocFile>/data/music/archive/1and1/content.json</tocFile>
                </metaDataPersistence>
            </localArchive>
            <localArchive>
                <rootPath>/data/music/archive/magenta1/media</rootPath>
                <archiveName>magenta1-${host}</archiveName>
                <metaDataPersistence>
                    <path>/data/music/archive/magenta1/metadata</path>
                    <tocFile>/data/music/archive/magenta1/content.json</tocFile>
                </metaDataPersistence>
            </localArchive>
        </localArchives>
    </media>
</configuration>
----

Information about local archives is located in a section named `localArchives`.
The section can contain a bunch of properties that define default settings
valid for all archives. Concrete archives are then defined by `localArchive`
elements within this section. In the definition of a local archive the same
properties can be used as in the `localArchives` section. Here an override
mechanism is in place: Properties that are not defined for a concrete archive
use the value set by the top-level section; and properties set for a local
archive override the values from the top-level section. Using this schema, it
is typically possible to define most of the default settings once in the
`localArchives` section, while concrete archive declarations can be kept to a
minimum (e.g. setting specific paths only).

Each local archive listed in the configuration can be given a descriptive name
using the _archiveName_ property. The name can be displayed by applications
allowing to browse archives. The archive name can contain a variable named
`${host}`, which is replaced by the IP-address of the local machine. This can
be useful if the content is exposed via a remote union archive.

The options available can be grouped into different categories and are
described in the following subsections. It does not matter whether an option is
defined as a default or for a specific local archive.

=== Location of media files

A number of options define where - on the local hard disk - media files can be
found:

.Configuration options for the location of media files
[cols="1,3",options="header"]
|============================
| Setting | Description
| excludedExtensions | With this list property (elements can be repeated as
often as necessary) the extensions of files can be specified which should be
ignored when scanning for media files. Such files are not included in media.
| includedExtensions | As an alternative to _excludedProperties_, with this
property a set of files extensions can be specified that are included; files
with other extensions are ignored. If both file extensions to include and to
exclude are specified, inclusions take precedence.
| infoSizeLimit | Files with information about a medium (typically called
`playlist.settings`) are fully read and processed in-memory. To avoid
unrestricted memory consumption, with this property a maximum file size (in
bytes) can be specified. Info files which are larger will not be processed.
| rootPath | This property defines the folder to be scanned for media files.
| processorCount | Defines the number of reader actors processing this folder
structure in parallel. If multiple archives are defined, the single archives
are processed one by one with this number of reader actors; so this property
defines the total number of parallel file reads.
| metaDataMediaBufferSize | A property determining the maximum size of the
buffer for media waiting to be processed for meta data extraction. During a
meta data scan operation, in a first step the content of media is determined.
Then the meta data for the files on the media is obtained (either from a
persistent storage or by meta data extraction). As this may take more time, the
number of media waiting to be processed for meta data extraction may increase.
This property defines a threshold for this number. When it is reached the scan
operation is blocked until media have been processed completely. This reduces
the amount of memory consumption during a scan operation. The property is
optional; a default value is used if it is not specified.
|============================

=== Settings related to scans for media files

These settings control the process of scanning a directory structure for media
files. Here the file system is traversed, media files are assigned to media
(identified by _medium description files_ with the file extension _.settings_),
and the description files are parsed to extract meta data about these media.
The settings are placed in a section named _scan_.

.Configuration options that control the scan process
[cols="1,3,1",options="header"]
|==============================
| Setting | Description | Default
| parseInfoTimeout | A timeout (in seconds) for parsing a medium description
file. If a parse operation takes longer than this time span, it is aborted and
dummy meta data is used for this medium. | 60 seconds
| mediaBufferSize | The size of the buffer for media to be processed in
parallel. When scanning a directory structure for media files some temporary
data is created for assignments of files to media, parsed description files,
etc. This property defines the number of temporary artifacts of those types
that can exist. If this limit is reached, stream processing pauses until the
limiting temporary artifacts have been processed. | 8
|==============================

=== Meta data extraction

The archive parses all detected media files in order to extract meta data
(e.g. ID3 tags) from them. With this group of options the behavior of this
meta data extraction process can be specified. The options are grouped in a
sub section named _metaDataExtraction_:

.Configuration options for meta data extraction
[cols="1,3",options="header"]
|============================
| Setting | Description
| metaDataExtraction.readChunkSize | Block size to be used when reading media
files. A buffer of this size is created in memory.
| metaDataExtraction.tagSizeLimit | Defines a maximum size of an ID3 tag to be
processed. Tags can become large, e.g. when they contain an image. The archive
only extracts text-based meta data. If a tag length is greater than this value,
it is ignored.
| metaDataExtraction.processingTimeout | Here a timeout (in seconds) for the
processing of a single media file can be specified. If meta data extraction for
this file takes longer, processing is aborted, and the file is ignored.
|============================

=== Meta data persistence

Once extracted, meta data is stored in files in JSON format on the local file
system. How this is done is specified with another group of options in the
_metaDataPersistence_ sub section:

.Configuration options for persisting meta data
[cols="1,3",options="header"]
|============================
| Setting | Description
| metaDataPersistence.path | Defines a path (on the local file system) where
files with extracted meta data information can be stored. Here files with the
extension `.mdt` (for meta data) are created containing the ID3 information
extracted from media files. These files are loaded when the archive starts up,
so that media files do not have to be scanned again.
| metaDataPersistence.chunkSize | Specifies the block size to be used when
reading or writing meta data files.
| metaDataPersistence.parallelCount | Here a number can be specified how many
meta data files are read in parallel. Increasing the number can speedup startup
time of the archive (provided that the local disc can handle the load).
| metaDataPersistence.writeBlockSize | If no persistent meta data file for a
medium is available, a new one is created automatically when the media files
from the medium are scanned. After some media files have been processed, an
`.mdt` file is written out, so that the information is already persisted in
case the scan is aborted. The _writeBlockSize_ property defines the number of
media files to be processed after the currently collected meta data is
persisted.
| metaDataPersistence.tocFile | A local archive can be configured to generate a
JSON file with a table of contents, i.e. a list with all media it contains and
their corresponding meta data files. This file has the same format as used by
an _HTTP archive_ to define its content. With the _tocFile_ property, the path
where to store the table of contents file can be specified. If it is missing,
no such file is generated.
|============================

= Local Media Archive Startup project

This module has the purpose to start the local media archive in an OSGi
environment.

== Description

This module is analogous to the startup project for the union archive, but
it is responsible for the _local media archive_. The local media archive
scans a folder structure with media files and passes the extracted meta data
to a union archive which can either run on the same JVM or is accessed
remotely.

Access to the union archive is obtained through the _client application
context_ available to all LineDJ platform components: actor references for the
actors implementing the archive are simply obtained from the _media facade_.
That way the location of the union archive is transparent.

The local archive is implemented by the following actors:

.Actors implementing the local archive
[cols="1,3",options="header"]
|==============================
| Actor class | Description
| ArchiveGroupActor | An actor managing a group of local paths that need to be
parsed for meta data files. For each path, the actor creates the other actors
for managing the media files. It is also responsible for the coordination of
scan operations.
| PersistentMetaDataManagerActor | The actor responsible for persistent meta
data files. It takes care that meta data extracted from media files is stored
on the local file system and is loaded again when the local archive restarts.
| MetaDataManagerActor | Controls the extraction of meta data from single media
files and sends the results to the union archive.
| MediaManagerActor | Scans a specified folder structure for media files and
collects information about media available. This information is sent to the
union archive.
|==============================

== Configuration

The configuration of the local media archive is also read from the
configuration file of the LineDJ management application (analogous as the
configuration for the union media archive; if both components are deployed in
the same platform container, they actually use the same configuration file,
and also their configuration sections overlap). The settings are placed in a
section named _media_. Below is an example fragment with all supported
configuration options:

[source,xml]
----
<configuration>
    <media>
        <mediaArchive>
            <metaDataUpdateChunkSize>32</metaDataUpdateChunkSize>
            <metaDataMaxMessageSize>128</metaDataMaxMessageSize>
        </mediaArchive>
        <localArchives>
            <processorCount>1</processorCount>
            <readerTimeout>3600</readerTimeout>
            <readerCheckInterval>600</readerCheckInterval>
            <readerCheckInitialDelay>480</readerCheckInitialDelay>
            <downloadChunkSize>16384</downloadChunkSize>
            <infoSizeLimit>32768</infoSizeLimit>
            <includedExtensions>MP3</includedExtensions>
            <scan>
                <parseInfoTimeout>10</parseInfoTimeout>
                <mediaBufferSize>3</mediaBufferSize>
            </scan>
            <metaDataExtraction>
                <readChunkSize>32768</readChunkSize>
                <tagSizeLimit>4096</tagSizeLimit>
                <metaDataUpdateChunkSize>8</metaDataUpdateChunkSize>
                <metaDataMaxMessageSize>160</metaDataMaxMessageSize>
                <processingTimeout>60</processingTimeout>
            </metaDataExtraction>
            <metaDataPersistence>
                <chunkSize>4096</chunkSize>
                <parallelCount>2</parallelCount>
                <writeBlockSize>40</writeBlockSize>
            </metaDataPersistence>
            <toc>
                <descRemovePrefix>/data/music/archive/media</descRemovePrefix>
                <descPathSeparator>/</descPathSeparator>
                <descUrlEncoding>true</descUrlEncoding>
                <rootPrefix>/music/archive/media</rootPrefix>
                <metaDataPrefix>/music/archive/metadata/</metaDataPrefix>
            </toc>
            <localArchive>
                <rootPath>/data/music/archive/1and1/media</rootPath>
                <archiveName>1and1-${host}</archiveName>
                <metaDataPersistence>
                    <path>/data/music/archive/1and1/metadata</path>
                </metaDataPersistence>
                <toc>
                    <file>/data/music/archive/1and1/content.json</file>
                    <descRemovePrefix>/data/music/archive/1and1/media</descRemovePrefix>
                </toc>
            </localArchive>
            <localArchive>
                <rootPath>/data/music/archive/magenta1/media</rootPath>
                <archiveName>magenta1-${host}</archiveName>
                <metaDataPersistence>
                    <path>/data/music/archive/magenta1/metadata</path>
                </metaDataPersistence>
                <toc>
                    <file>/data/music/archive/magenta1/content.json</file>
                    <descRemovePrefix>/data/music/archive/magenta1/media</descRemovePrefix>
                </toc>
            </localArchive>
        </localArchives>
    </media>
</configuration>
----

Information about local archives is located in a section named `localArchives`.
The section can contain a bunch of properties that define default settings
valid for all archives. Concrete archives are then defined by `localArchive`
elements within this section. In the definition of a local archive the same
properties can be used as in the `localArchives` section. Here an override
mechanism is in place: Properties that are not defined for a concrete archive
use the value set by the top-level section; and properties set for a local
archive override the values from the top-level section. Using this schema, it
is typically possible to define most of the default settings once in the
`localArchives` section, while concrete archive declarations can be kept to a
minimum (e.g. setting specific paths only).

Each local archive listed in the configuration can be given a descriptive name
using the _archiveName_ property. The name can be displayed by applications
allowing to browse archives. The archive name can contain a variable named
`${host}`, which is replaced by the IP-address of the local machine. This can
be useful if the content is exposed via a remote union archive.

The options available can be grouped into different categories and are
described in the following subsections. It does not matter whether an option is
defined as a default or for a specific local archive.

=== Location of media files

A number of options define where - on the local hard disk - media files can be
found:

.Configuration options for the location of media files
[cols="1,3",options="header"]
|============================
| Setting | Description
| excludedExtensions | With this list property (elements can be repeated as
often as necessary) the extensions of files can be specified which should be
ignored when scanning for media files. Such files are not included in media.
| includedExtensions | As an alternative to _excludedProperties_, with this
property a set of files extensions can be specified that are included; files
with other extensions are ignored. If both file extensions to include and to
exclude are specified, inclusions take precedence.
| infoSizeLimit | Files with information about a medium (typically called
`playlist.settings`) are fully read and processed in-memory. To avoid
unrestricted memory consumption, with this property a maximum file size (in
bytes) can be specified. Info files which are larger will not be processed.
| rootPath | This property defines the folder to be scanned for media files.
| processorCount | Defines the number of reader actors processing this folder
structure in parallel. If multiple archives are defined, the single archives
are processed one by one with this number of reader actors; so this property
defines the total number of parallel file reads.
| metaDataMediaBufferSize | A property determining the maximum size of the
buffer for media waiting to be processed for meta data extraction. During a
meta data scan operation, in a first step the content of media is determined.
Then the meta data for the files on the media is obtained (either from a
persistent storage or by meta data extraction). As this may take more time, the
number of media waiting to be processed for meta data extraction may increase.
This property defines a threshold for this number. When it is reached the scan
operation is blocked until media have been processed completely. This reduces
the amount of memory consumption during a scan operation. The property is
optional; a default value is used if it is not specified.
|============================

=== Settings related to scans for media files

These settings control the process of scanning a directory structure for media
files. Here the file system is traversed, media files are assigned to media
(identified by _medium description files_ with the file extension _.settings_),
and the description files are parsed to extract meta data about these media.
The settings are placed in a section named _scan_.

.Configuration options that control the scan process
[cols="1,3,1",options="header"]
|==============================
| Setting | Description | Default
| parseInfoTimeout | A timeout (in seconds) for parsing a medium description
file. If a parse operation takes longer than this time span, it is aborted and
dummy meta data is used for this medium. | 60 seconds
| mediaBufferSize | The size of the buffer for media to be processed in
parallel. When scanning a directory structure for media files some temporary
data is created for assignments of files to media, parsed description files,
etc. This property defines the number of temporary artifacts of those types
that can exist. If this limit is reached, stream processing pauses until the
limiting temporary artifacts have been processed. | 8
|==============================

=== Meta data extraction

The archive parses all detected media files in order to extract meta data
(e.g. ID3 tags) from them. With this group of options the behavior of this
meta data extraction process can be specified. The options are grouped in a
sub section named _metaDataExtraction_:

.Configuration options for meta data extraction
[cols="1,3",options="header"]
|============================
| Setting | Description
| metaDataExtraction.readChunkSize | Block size to be used when reading media
files. A buffer of this size is created in memory.
| metaDataExtraction.tagSizeLimit | Defines a maximum size of an ID3 tag to be
processed. Tags can become large, e.g. when they contain an image. The archive
only extracts text-based meta data. If a tag length is greater than this value,
it is ignored.
| metaDataExtraction.processingTimeout | Here a timeout (in seconds) for the
processing of a single media file can be specified. If meta data extraction for
this file takes longer, processing is aborted, and the file is ignored.
|============================

=== Meta data persistence

Once extracted, meta data is stored in files in JSON format on the local file
system. How this is done is specified with another group of options in the
_metaDataPersistence_ sub section:

.Configuration options for persisting meta data
[cols="1,3",options="header"]
|============================
| Setting | Description
| metaDataPersistence.path | Defines a path (on the local file system) where
files with extracted meta data information can be stored. Here files with the
extension `.mdt` (for meta data) are created containing the ID3 information
extracted from media files. These files are loaded when the archive starts up,
so that media files do not have to be scanned again.
| metaDataPersistence.chunkSize | Specifies the block size to be used when
reading or writing meta data files.
| metaDataPersistence.parallelCount | Here a number can be specified how many
meta data files are read in parallel. Increasing the number can speedup startup
time of the archive (provided that the local disc can handle the load).
| metaDataPersistence.writeBlockSize | If no persistent meta data file for a
medium is available, a new one is created automatically when the media files
from the medium are scanned. After some media files have been processed, an
`.mdt` file is written out, so that the information is already persisted in
case the scan is aborted. The _writeBlockSize_ property defines the number of
media files to be processed after the currently collected meta data is
persisted.
|============================

=== Archive table of contents

A local archive can be configured to generate a JSON file with a table of
contents, i.e. a list with all media it contains and their corresponding meta
data files. This file has the same format as used by an _HTTP archive_ to
define its content.

The options are declared in a sub section named _toc_. They are optional; the
ToC file is generated only if a target file is specified.

.Configuration options for the table of contents
[cols="1,3",options="header"]
|============================
| Setting | Description
| file | Defines the location where the table of contents file is to be stored.
If this property is missing, no such file is generated.
| descRemovePrefix | The paths to the single media contained in the archive are
typically absolute paths. For some use cases, e.g. if they are to be exposed
via an HTTP server, they have to be converted to relative URIs. This property
defines the prefix of the paths that must be removed for this purpose. Note
that only media are included in the ToC document whose path starts with this
prefix. If no prefix is specified, the whole paths to media are used.
| descRemovePathComponents | After the path to a medium description file has
been processed (by removing the prefix and converting it to a URI), it is
possible to strip off a number of URI path components from the beginning. The
number of components to remove can be specified using this property. The
default value is 0; so no components will be removed.
| descPathSeparator | The path separator used in paths to media description
files. This is typically the slash on Linux and the backslash on Windows.
| descUrlEncoding | A flag whether URL encoding should be applied to paths to
media. If the media should be exposed via an HTTP server, this is typically
needed.
| rootPrefix | Here a prefix can be specified which is added to paths to media
files. That way, they can be referenced correctly, even if they are stored in a
sub folder structure.
| metaDataPrefix | Analogous to _rootPrefix_, this a prefix added to meta data
files. Such files may be stored in a dedicated folder; with this prefix, the
folder can be selected.
|============================


Fluentd examples are using etcd pod names

// Module included in the following assemblies:
//
// * logging/efk-logging-fluentd.adoc

[id="efk-logging-fluentd-log-viewing-{context}"]
= Viewing Fluentd logs

How you view logs depends upon the `LOGGING_FILE_PATH` setting.

* If `LOGGING_FILE_PATH` points to a file, the default, use the *logs* utility, from the project,
where the pod is located, to print out the contents of Fluentd log files:
+
----
$ oc exec <any-fluentd-pod> -- logs <1>
----
<1> Specify the name of a Fluentd pod. Note the space before `logs`.
+
For example:
+
----
$ oc exec fluentd-ht42r -n openshift-logging -- logs
----
+
To view the current setting:
+
----
oc -n openshift-logging set env daemonset/fluentd --list | grep LOGGING_FILE_PATH
----

* If you are using `LOGGING_FILE_PATH=console`,  Fluentd writes logs to stdout/stderr`.
You can retrieve the logs with the `oc logs [-f] <pod_name>` command, where the `-f`
is optional, from the project where the pod is located.
+
----
$ oc logs -f <any-fluentd-pod> <1>
----
<1> Specify the name of a Fluentd pod. Use the `-f` option to follow what is being written into the logs.
+
For example
+
----
$ oc logs -f fluentd-ht42r -n openshift-logging
----
+
The contents of log files are printed out, starting with the oldest log.

// Module included in the following assemblies:
//
// * logging/efk-logging-fluentd.adoc

[id="efk-logging-fluentd-log-viewing-{context}"]
= Viewing Fluentd logs

How you view logs depends upon the `LOGGING_FILE_PATH` setting.

* If `LOGGING_FILE_PATH` points to a file, the default, use the *logs* utility, from the project,
where the pod is located, to print out the contents of Fluentd log files:
+
----
$ oc exec <pod> -- logs <1>
----
<1> Specify the name of the Fluentd pod. Note the space before `logs`.
+
For example:
+
----
$ oc exec etcd-member-ip-30.ec2.internal -n kube-system -- logs
----
+
To view the current setting:
+
----
oc -n openshift-logging set env daemonset/fluentd --list | grep LOGGING_FILE_PATH
----

* If you are using `LOGGING_FILE_PATH=console`,  Fluentd writes logs to stdout/stderr`.
You can retrieve the logs with the `oc logs [-f] <pod_name>` command, where the `-f`
is optional, from the project where the pod is located.
+
----
$ oc logs -f <pod> <1>
----
<1> Specify the name of the Fluentd pod. Use `-f` option to follow what is being written into the logs.
+
For example
+
----
$ oc logs -f etcd-member-ip-30.ec2.internal -n kube-system
----
+
The contents of log files are printed out, starting with the oldest log.