Skip to content

Commit 32d563f

Browse files
author
Glyn Normington
committed
[#52324579]Add migration guide
The migration guide documents how to migrate from the previous Java buildpack. The migration notes include intentional migration impacts and some features which are still required to bring the new buildpack up to parity with the old buildpack. The latter are flagged as temporary restrictions. Note in the OpenJDK documentation that $MEMORY_LIMIT is not yet passed to the buildpack.
1 parent 1a2a601 commit 32d563f

5 files changed

Lines changed: 75 additions & 9 deletions

File tree

‎README.md‎

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -8,22 +8,19 @@ The `java-buildpack` is a [Cloud Foundry][cf] buildpack for running Java applica
88
[cf]: http://www.cloudfoundry.com
99

1010
## Usage
11-
To use this buildpack specify the URI of the repository when pushing an application to Cloud Foundry.
11+
To use this buildpack specify the URI of the repository when pushing an application to Cloud Foundry:
1212

13-
```bash
14-
cf push --buildpack https://github.com/cloudfoundry/java-buildpack
15-
```
13+
cf push --buildpack https://github.com/cloudfoundry/java-buildpack
1614

1715
## Configuration and Extension
18-
The buildpack supports configuration and extension through the use of Git repository forking. The easiest way to accomplish this is to use [GitHub's forking functionality][fork] to create a copy of this repository. In that copy of the repository, make the required configuration and extension changes. Then when pushing a Cloud Foundry application, use the URL of the new repository. If the modifications are applicable to the Cloud Foundry community, please submit a [pull request][pull-request] with the changes.
16+
The buildpack supports configuration and extension through the use of Git repository forking. The easiest way to accomplish this is to use [GitHub's forking functionality][fork] to create a copy of this repository. Make the required configuration and extension changes in the copy of the repository. Then specify the URL of the new repository when pushing Cloud Foundry applications. If the modifications are generally applicable to the Cloud Foundry community, please submit a [pull request][pull-request] with the changes.
1917

2018
[fork]: https://help.github.com/articles/fork-a-repo
2119
[pull-request]: https://help.github.com/articles/using-pull-requests
2220

2321
## Additional Documentation
24-
Additional documentation can be found by following the links below.
25-
2622
* [Design](docs/design.md)
23+
* [Migrating from the Previous Java Buildpack](docs/migration.md)
2724
* Standard Containers
2825
* [Java Main Class](docs/container-java-main.md) ([Configuration](docs/container-java-main.md#configuration))
2926
* [Play](docs/container-play.md)

‎docs/container-java-main.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ Command line arguments may optionally be configured.
77

88
<table>
99
<tr>
10-
<td><strong>Detection Criteria</strong></td><td><tt>Main-Class</tt> attribute set in <tt>META-INF/MANIFEST.MF</tt> or <tt>java_main_class</tt> set</td>
10+
<td><strong>Detection Criteria</strong></td><td><tt>Main-Class</tt> attribute set in <tt>META-INF/MANIFEST.MF</tt> or <tt>java_main_class</tt> set in [`config/main.yml`][main_yml]</td>
1111
</tr>
1212
<tr>
1313
<td><strong>Tags</strong></td><td><tt>java-main</tt></td>

‎docs/container-play.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ The Play Container allows Play applications to be run.
33

44
<table>
55
<tr>
6-
<td><strong>Detection Criteria</strong></td><td>The files <tt>start</tt> and <tt>lib/play.play_*.jar</tt> exist in the application</td>
6+
<td><strong>Detection Criteria</strong></td><td>The files <tt>start</tt> and <tt>lib/play.play_*.jar</tt> (or <tt>staged/play.play_*.jar</tt>) exist in the application</td>
77
</tr>
88
<tr>
99
<td><strong>Tags</strong></td><td><tt>Play</tt></td>

‎docs/jre-openjdk.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,3 +48,5 @@ If some memory sizes are not specified using the above properties, default value
4848
If a memory size is specified which is not equal to the default value, the other default values are adjusted proportionately, except that the default stack size is never adjusted.
4949

5050
The default memory size proportions are configured in the `memory_heuristics` mapping of [`config/openjdk.yml`][openjdk_yml]. Each memory size is given a weighting between `0` and `1` corresponding to a proportion of the total memory specified when the application was pushed. The weightings should add up to `1`.
51+
52+
Currently, Cloud Foundry does not make the application memory limit (`$MEMORY_LIMIT`) available to the buildpack, so only the stack size is defaulted.

‎docs/migration.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Important notice: this buildpack has temporary restrictions which are detailed below.
2+
3+
# Migrating from cloudfoundry-buildpack-java
4+
5+
This buildpack supersedes the buildpack [`cloudfoundry-buildpack-java`](https://github.com/cloudfoundry/cloudfoundry-buildpack-java) but is not backward
6+
compatible with it, so users should read the following migration notes.
7+
8+
## Detect Processing
9+
10+
`cloudfoundry-buildpack-java` had different detection rules to this buildpack. It performed a sequence of detection checks and acted upon the first check, if any, which passed. So it paid no attention to
11+
potentially ambiguous results.
12+
13+
This buildpack ensures that at most one _container_ (see [Design](design.md) for the definition of this term) can be used to run an application and raises an error if more than one container can be used.
14+
15+
This buildpack supports all the types of application that `cloudfoundry-buildpack-java` supported. However, this buildpack distinguishes between _containers_ and orthogonal _frameworks_ (see [Design](design.md) for the definition of this term) whereas `cloudfoundry-buildpack-java` merged these concepts.
16+
17+
## All Application Types
18+
19+
<b>Temporary restriction:</b> this buildpack does not yet support the Spring `cloud`
20+
namespace for direct binding to Cloud Foundry services or Spring auto-reconfiguration
21+
for automatic re-binding to such services.
22+
23+
## Play Applications
24+
25+
`cloudfoundry-buildpack-java` allowed the Play `start` script (and the application's `lib` directory,
26+
although this is ignored during detection) to reside in an arbitrary subdirectory of the application directory.
27+
This buildpack requires the `start` script and the `lib` directory (or, equivalently, the `staged` directory) to reside directly in the application directory. If it is more convenient
28+
to push the application from another directory, use the `path` parameter of `cf push` to specify the
29+
directory containing the `start` script. This avoids needlessly uploading additional files.
30+
31+
<b>Temporary restriction:</b> this buildpack does not yet support Play applications that use JPA.
32+
33+
## Grails Applications
34+
35+
The support for Grails applications in this buildpack is identical to the support for standard web
36+
applications.
37+
38+
## Web Applications
39+
40+
`cloudfoundry-buildpack-java` allowed `web.xml` to reside in either of the directories `WEB-INF` or `webapps/ROOT/WEB-INF` whereas this buildpack requires `web.xml` to reside in the `WEB-INF` directory.
41+
42+
`cloudfoundry-buildpack-java` was hard-coded to use a specific version of Tomcat. This buildpack is configured
43+
to use the latest update of a particular version of Tomcat. If a specific version of Tomcat is required,
44+
configure it in `config/tomcat.yml`.
45+
46+
`cloudfoundry-buildpack-java` automatically configured listeners with class names `org.apache.catalina.core.JreMemoryLeakPreventionListener` and
47+
`org.apache.catalina.mbeans.GlobalResourcesLifecycleListener`.
48+
`JreMemoryLeakPreventionListener` is not necessary since the memory leaks it prevents do not occur in Cloud Foundry.
49+
`GlobalResourcesLifecycleListener` is not necessary since Cloud Foundry applications are not managed
50+
using JMX.
51+
52+
<b>Temporary restriction:</b> `cloudfoundry-buildpack-java` automatically downloaded hard-coded versions of MySQL and PostGres database driver JARs and added them to the `lib` directory of the application, whereas this buildpack does not yet download or add database driver JARs.
53+
54+
## Java Main Applications
55+
56+
`cloudfoundry-buildpack-java` required Java main applications to contain a `.jar` or a `.class` file somewhere in the
57+
application directory tree whereas this buildpack requires either the `Main-Class` attribute to be set
58+
in `META-INF/MANIFEST.MF` or `java_main_class` to be configured in `config/main.yml`.
59+
60+
`cloudfoundry-buildpack-java` used a version of OpenJDK specified as the property `java.runtime.version` in a file `system.properties` residing anywhere in the application directory tree. If this property was not specified, `cloudfoundry-buildpack-java` used a hard-coded version of OpenJDK. This buildpack is configured
61+
to use the latest update of a particular version of OpenJDK. If a specific version of OpenJDK is required,
62+
configure it in `config/openjdk.yml`. The version of OpenJDK may no longer be specified using a system property.
63+
64+
`cloudfoundry-buildpack-java` configured both the JVM maximum and minimum heap sizes to equal the application memory limit (`$MEMORY_LIMIT`). This buildpack supports a variety of memory size settings and memory heuristic settings for calculating defaults based on the application memory limit. See [OpenJDK JRE configuration](jre-openjdk.md#configuration) for details.
65+
66+
`cloudfoundry-buildpack-java` used to set the `java.io.tmpdir` Java system property to `$TMPDIR`. If this is required, configure [`java_opts`](framework-java_opts.md#configuration).
67+

0 commit comments

Comments
 (0)