Documentation

You are viewing the documentation for Play 1. The documentation for Play 2 is here.

Dependency management

Play’s dependency management system allows you to express your application’s external dependencies in a single dependencies.yml file.

A Play application can have three kinds of dependencies:

Once you have expressed these dependencies in your application’s conf/dependencies.yml file, Play will resolve, download and install all required dependencies.

Dependency format

A dependency is described by an organisation a name and a revision number. In the dependencies.yml file you will write it like this:

organisation -> name revision

So, for instance version 1.0 of the Play PDF module is expressed like this:

play -> pdf 1.0

Sometimes the organisation name exactly matches the dependency name, as is the case for commons-lang:

commons-lang -> commons-lang 2.5

In this case, you can omit the organisation from the dependency declaration:

commons-lang 2.5

Dynamic revisions

The revision can be fixed (1.2, for instance) or dynamic. A dynamic revision expresses a range of allowed revisions.

For example:

dependencies.yml

When you create a new Play application, a dependencies.yml descriptor is automatically created in the conf/ directory:

# Application dependencies
    
require:
    - play 1.2

The require section list all dependencies needed by your application. Here the new application only depends on Play version 1.2. But let’s say your application needs Google Guava; you would have:

# Application dependencies
    
require:
    - play 1.2
    - com.google.guava -> guava r07

The ‘play dependencies’ command

To ask Play to resolve, download and install the new dependencies, run play dependencies:

$ play dependencies
~        _            _ 
~  _ __ | | __ _ _  _| |
~ | '_ \| |/ _' | || |_|
~ |  __/|_|\____|\__ (_)
~ |_|            |__/   
~
~ play! 1.2, http://www.playframework.org
~ framework ID is gbo
~
~ Resolving dependencies using ~/Documents/coco/conf/dependencies.yml,
~
~ 	com.google.guava->guava r07 (from mavenCentral)
~ 	com.google.code.findbugs->jsr305 1.3.7 (from mavenCentral)
~
~ Downloading required dependencies,
~
~ 	downloaded http://repo1.maven.org/maven2/com/google/guava/guava/r07/guava-r07.jar
~ 	downloaded http://repo1.maven.org/maven2/com/google/code/findbugs/jsr305/1.3.7/jsr305-1.3.7.jar
~
~ Installing resolved dependencies,
~
~ 	lib/guava-r07.jar
~ 	lib/jsr305-1.3.7.jar
~
~ Done!
~

Now Play has downloaded two JARs (guava-r07.jar, jsr305-1.3.7.jar) from the central Maven repository, and installed them into the application lib/ directory.

Why two jars, since we only declared one dependency? Because Google Guava has a transitive dependency. In fact this dependency is not really required and we would like to exclude it.

Transitive dependencies

By default, any transitive dependencies are automatically retrieved. But there are several ways to exclude them if needed.

1. You can disable transitive dependencies for a particular dependency:

# Application dependencies
    
require:
    - play 1.2
    - com.google.guava -> guava r07:
        transitive: false

2. You can disable transitive dependencies for the whole project:

# Application dependencies
    
transitiveDependencies: false    
    
require:
    - play 1.2
    - com.google.guava -> guava r07

3. You can exclude any specific dependency explicitely:

# Application dependencies
    
require:
    - play 1.2
    - com.google.guava -> guava r07:
        exclude:
            - com.google.code.findbugs -> *

Keep lib/ and modules/ directory in sync

Now if you run play dependencies again, the findbugs dependency will be omitted:

$ play deps
~        _            _ 
~  _ __ | | __ _ _  _| |
~ | '_ \| |/ _' | || |_|
~ |  __/|_|\____|\__ (_)
~ |_|            |__/   
~
~ play! 1.2, http://www.playframework.org
~ framework ID is gbo
~
~ Resolving dependencies using ~/Documents/coco/conf/dependencies.yml,
~
~ 	com.google.guava->guava r07 (from mavenCentral)
~
~ Installing resolved dependencies,
~
~ 	lib/guava-r07.jar
~
~ ********************************************************************
~ WARNING: Your lib/ and modules/ directories and not synced with 
~ current dependencies (use --sync to automatically delete them)
~
~ 	Unknown: ~/Documents/coco/lib/jsr305-1.3.7.jar
~ ********************************************************************
~
~ Done!
~

However the jsr305-1.3.7.jar artifact downloaded before is still present in the application lib/ directory.

To keep the lib/ and modules/ directory synced with the dependency management system, you can specify the --sync command to the dependencies command:

play dependencies --sync

If you run this command again the unwanted JAR will be deleted.

Conflict resolution

Whenever two components need different revisions of the same dependency, the conflicts manager will choose one. The default is to keep the latest revision and to evict the others.

But there is an exception. When a core dependency of Play framework itself is involved in a conflict, the version available in $PLAY/framework/lib is preferred. For instance, Play depends on commons-lang 2.5. If your application requires commons-lang 3.0:

# Application dependencies
    
require:
    - play 1.2
    - com.google.guava -> guava r07:
        transitive: false
    - commons-lang 3.0

Running play dependencies will evict commons-lang 3.0 even if this version is newer:

play dependencies
~        _            _ 
~  _ __ | | __ _ _  _| |
~ | '_ \| |/ _' | || |_|
~ |  __/|_|\____|\__ (_)
~ |_|            |__/   
~
~ play! 1.2, http://www.playframework.org
~ framework ID is gbo
~
~ Resolving dependencies using ~/Documents/coco/conf/dependencies.yml,
~
~ 	com.google.guava->guava r07 (from mavenCentral)
~
~ Some dependencies have been evicted,
~
~	commons-lang 3.0 is overriden by commons-lang 2.5
~
~ Installing resolved dependencies,
~
~ 	lib/guava-r07.jar
~
~ Done!
~

Also, note that dependencies already available in $PLAY/framework/lib will not be installed in your application’s lib/ directory.

Sometimes you want to force a specific dependency version, either to override a core dependency or to choose another revision that the latest version available.

So you can specify the force option on any dependency:

# Application dependencies
    
require:
    - play 1.2
    - com.google.guava -> guava r07:
        transitive: false
    - commons-lang 3.0:
        force: true

Adding new repositories

By default, Play will search for JAR dependencies in the central Maven repository, and will search for Play modules in the central Play modules repository.

You can, of course, specify new custom repositories in the repositories section:

# Application dependencies
    
require:
    - play 1.2
    - com.google.guava -> guava r07:
        transitive: false
    - commons-lang 3.0:
        force: true
    - com.zenexity -> sso 1.0
        
# My custom repositories
repositories:
    
    - zenexity:
        type:       http
        artifact:   "http://www.zenexity.com/repo/[module]-[revision].[ext]"
        contains:
            - com.zenexity -> *

Using this configuration all dependencies of the com.zenexity organisation will be retrieved and downloaded from a remote HTTP server.

Maven repositories

You can also add maven2-compatible repositories using the iBiblio type, like this:

# Application dependencies
    
require:
    - play
    - play -> scala 0.8
    - org.jbpm -> jbpm-persistence-jpa 5.0.0:
        exclude:
            - javassist -> javassist *
            - org.hibernate -> hibernate-annotations *
            - javax.persistence -> persistence-api *
repositories:
    - jboss:
        type: iBiblio
        root: "http://repository.jboss.org/nexus/content/groups/public-jboss/"
        contains:
            - org.jbpm -> *
            - org.drools -> *

Local repositories

Finally and probably foremost, you may want to define a repository that references local modules. With this scenario, dependencies work very much like application.conf’s module resolution (now deprecated).

So given the following folder structure,

myplayapp/
myfirstmodule/
mysecondmodule/

The following myplayapp/conf/depencencies.yml will achieve its goal.

# Application dependencies
    
require:
    - play
    - myfirstmodule -> myfirstmodule
    - mysecondmodule -> mysecondmodule
    
repositories:
    - My modules:
        type:       local
        artifact:   ${application.path}/../[module]
        contains:
            - myfirstmodule
            - mysecondmodule

Note: don’t forget to run play dependencies myplayapp.

Custom ivy settings

Play is using Ivy under the hood. If you require a special configuration such as setting a proxy, basic authentication for an internal maven nexus repository, you can edit the ivysettings.xml file. It is located in the .ivy2 folder in your home directory.

Example1, you want ivy to ignore checksums:
# .ivy2/ivysettings.xml
<ivysettings>
  <property name="ivy.checksums" value=""/>
</ivysettings>

Example2, you want to use basic auth:
# .ivy2/ivysettings.xml
<ivysettings>
  <credentials host="maven-repo.xxx" realm="Sonatype Nexus Repository Manager" username="user" passwd="reallygreatpassword"/>
</ivysettings>

There are many things you can configure see: http://ant.apache.org/ivy/history/2.1.0/settings.html

Continuing the discussion

Next: Database evolutions.