Skip to content

Commit a1ea289

Browse files
committed
Documentation of new abstractions
This change adds documentation for the new Application and Droplet abstractions. [#61738342]
1 parent bf95618 commit a1ea289

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

49 files changed

+791
-433
lines changed

README.md

+33-21
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,15 @@ The `java-buildpack` is a [Cloud Foundry][] buildpack for running Java applicati
88
## Usage
99
To use this buildpack specify the URI of the repository when pushing an application to Cloud Foundry:
1010

11-
cf push --buildpack https://github.com/cloudfoundry/java-buildpack
11+
```bash
12+
cf push --buildpack https://github.com/cloudfoundry/java-buildpack
13+
```
14+
15+
or if using the [`gcf`][] tool:
1216

13-
The total amount of memory available is specified when the application is pushed. See [Memory](docs/jre-openjdk.md#Memory) for information on how this determines the memory available to a Java application.
17+
```bash
18+
gcf push -b https://github.com/cloudfoundry/java-buildpack
19+
```
1420

1521
## Configuration and Extension
1622
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][] 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][] with the changes.
@@ -19,33 +25,38 @@ To learn how to configure various properties of the buildpack, follow the "Confi
1925

2026
## Additional Documentation
2127
* [Design](docs/design.md)
22-
* [Migrating from the Previous Java Buildpack](docs/migration.md)
2328
* [Security](docs/security.md)
2429
* Standard Containers
2530
* [Groovy](docs/container-groovy.md) ([Configuration](docs/container-groovy.md#configuration))
26-
* [Java Main Class](docs/container-java-main.md) ([Configuration](docs/container-java-main.md#configuration))
27-
* [Play](docs/container-play.md)
28-
* [Spring Boot CLI](docs/container-spring-boot-cli.md) ([Configuration](docs/container-spring-boot-cli.md#configuration))
31+
* [Java Main](docs/container-java_main.md) ([Configuration](docs/container-java_main.md#configuration))
32+
* [Play Framework](docs/container-play_framework.md)
33+
* [Spring Boot CLI](docs/container-spring_boot_cli.md) ([Configuration](docs/container-spring_boot_cli.md#configuration))
2934
* [Tomcat](docs/container-tomcat.md) ([Configuration](docs/container-tomcat.md#configuration))
3035
* Standard Frameworks
36+
* [AppDynamics Agent](docs/framework-app_dynamics_agent.md) ([Configuration](docs/framework-app_dynamics_agent.md#configuration))
3137
* [Java Options](docs/framework-java_opts.md) ([Configuration](docs/framework-java_opts.md#configuration))
32-
* [AppDynamics](docs/framework-app-dynamics.md) ([Configuration](docs/framework-app-dynamics.md#configuration))
33-
* [New Relic](docs/framework-new-relic.md) ([Configuration](docs/framework-new-relic.md#configuration))
34-
* [Play Auto Reconfiguration](docs/framework-play-auto-reconfiguration.md) ([Configuration](docs/framework-play-auto-reconfiguration.md#configuration))
35-
* [Play JPA Plugin](docs/framework-play-jpa-plugin.md) ([Configuration](docs/framework-play-jpa-plugin.md#configuration))
36-
* [Spring Auto Reconfiguration](docs/framework-spring-auto-reconfiguration.md) ([Configuration](docs/framework-spring-auto-reconfiguration.md#configuration))
37-
* [Spring Insight](docs/framework-spring-insight.md) ([Configuration](docs/framework-spring-insight.md#configuration))
38+
* [MariaDB JDBC](docs/framework-maria_db_jdbc.md) ([Configuration](docs/framework-maria_db_jdbc.md#configuration))
39+
* [New Relic Agent](docs/framework-new_relic_agent.md) ([Configuration](docs/framework-new_relic_agent.md#configuration))
40+
* [Play Framework Auto Reconfiguration](docs/framework-play_framework_auto_reconfiguration.md) ([Configuration](docs/framework-play_framework_auto_reconfiguration.md#configuration))
41+
* [Play Framework JPA Plugin](docs/framework-play_framework_jpa_plugin.md) ([Configuration](docs/framework-play_framework_jpa_plugin.md#configuration))
42+
* [PostgreSQL JDBC](docs/framework-postgresql_jdbc.md) ([Configuration](docs/framework-postgresql_jdbc.md#configuration))
43+
* [Spring Auto Reconfiguration](docs/framework-spring_auto_reconfiguration.md) ([Configuration](docs/framework-spring_auto_reconfiguration.md#configuration))
44+
* [Spring Insight](docs/framework-spring_insight.md)
3845
* Standard JREs
39-
* [OpenJDK](docs/jre-openjdk.md) ([Configuration](docs/jre-openjdk.md#configuration))
46+
* [OpenJDK](docs/jre-open_jdk.md) ([Configuration](docs/jre-open_jdk.md#configuration))
4047
* [Extending](docs/extending.md)
41-
* Utilities
42-
* [Caches](docs/util-caches.md) ([Configuration](docs/util-caches.md#configuration))
43-
* [Logging](docs/logging.md) ([Configuration](docs/logging.md#configuration))
44-
* [Repositories](docs/util-repositories.md) ([Configuration](docs/util-repositories.md#configuration))
45-
* [Other Utiltities](docs/util-other.md)
46-
* [Repository Builder](docs/util-repository-builder.md)
47-
* [Test Applications](docs/util-test-applications.md)
48-
* [System Tests](docs/util-system-tests.md)
48+
* [Application](docs/extending-application.md)
49+
* [Droplet](docs/extending-droplet.md)
50+
* [BaseComponent](docs/extending-base_component.md)
51+
* [VersionedDependencyComponent](docs/extending-versioned_dependency_component.md)
52+
* [Caches](docs/extending-caches.md) ([Configuration](docs/extending-caches.md#configuration))
53+
* [Logging](docs/extending-logging.md) ([Configuration](docs/extending-logging.md#configuration))
54+
* [Repositories](docs/extending-repositories.md) ([Configuration](docs/extending-repositories.md#configuration))
55+
* [Utiltities](docs/extending-utiltities.md)
56+
* Related Projects
57+
* [Java Buildpack Dependency Builder](https://github.com/cloudfoundry/java-buildpack-dependency-builder)
58+
* [Java Test Applications](https://github.com/cloudfoundry/java-test-applications)
59+
* [Java Buildpack System Tests](https://github.com/cloudfoundry/java-buildpack-system-test)
4960

5061
## Running Tests
5162
To run the tests, do the following:
@@ -66,6 +77,7 @@ This buildpack is released under version 2.0 of the [Apache License][].
6677
[Apache License]: http://www.apache.org/licenses/LICENSE-2.0
6778
[Cloud Foundry]: http://www.cloudfoundry.com
6879
[contributor guidelines]: CONTRIBUTING.md
80+
[`gcf`]: https://github.com/cloudfoundry/cli
6981
[GitHub's forking functionality]: https://help.github.com/articles/fork-a-repo
7082
[pull request]: https://help.github.com/articles/using-pull-requests
7183
[Pull requests]: http://help.github.com/send-pull-requests

config/components.yml

+2-2
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,8 @@ frameworks:
2828
- "JavaBuildpack::Framework::JavaOpts"
2929
- "JavaBuildpack::Framework::MariaDbJDBC"
3030
- "JavaBuildpack::Framework::NewRelicAgent"
31-
- "JavaBuildpack::Framework::PlayAutoReconfiguration"
32-
- "JavaBuildpack::Framework::PlayJPAPlugin"
31+
- "JavaBuildpack::Framework::PlayFrameworkAutoReconfiguration"
32+
- "JavaBuildpack::Framework::PlayFrameworkJPAPlugin"
3333
- "JavaBuildpack::Framework::PostgresqlJDBC"
3434
- "JavaBuildpack::Framework::SpringAutoReconfiguration"
3535
- "JavaBuildpack::Framework::SpringInsight"
File renamed without changes.

docs/container-groovy.md

+5-4
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# Groovy Container
2-
The Groovy Container allows a uncompiled (i.e. `*.groovy`) to be run.
2+
The Groovy Container allows uncompiled Groovy files (i.e. `*.groovy`) to be run.
33

44
<table>
55
<tr>
@@ -13,7 +13,8 @@ The Groovy Container allows a uncompiled (i.e. `*.groovy`) to be run.
1313
</ul></td>
1414
</tr>
1515
<tr>
16-
<td><strong>Tags</strong></td><td><tt>groovy=&lang;version&rang;</tt></td>
16+
<td><strong>Tags</strong></td>
17+
<td><tt>groovy=&lang;version&rang;</tt></td>
1718
</tr>
1819
</table>
1920
Tags are printed to standard output by the buildpack detect script
@@ -30,6 +31,6 @@ The container can be configured by modifying the [`config/groovy.yml`][] file.
3031

3132
[Configuration and Extension]: ../README.md#Configuration-and-Extension
3233
[`config/groovy.yml`]: ../config/groovy.yml
33-
[repositories]: util-repositories.md
34+
[repositories]: extending-repositories.md
3435
[this listing]: http://download.pivotal.io.s3.amazonaws.com/groovy/index.yml
35-
[version syntax]: util-repositories.md#version-syntax-and-ordering
36+
[version syntax]: extending-repositories.md#version-syntax-and-ordering
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
1-
# Java Main Class Container
2-
The Java Main Class Container allows an application that provides a class with a `main()` method to be run. The application is executed with a command of the form:
1+
# Java Main Container
2+
The Java Main Container allows an application that provides a class with a `main()` method to be run. The application is executed with a command of the form:
33

4-
./java/bin/java -cp . com.gopivotal.SampleClass
4+
```bash
5+
<JAVA_HOME>/bin/java -cp . com.gopivotal.SampleClass
6+
```
57

68
Command line arguments may optionally be configured.
79

@@ -10,25 +12,23 @@ Command line arguments may optionally be configured.
1012
<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 <a href="../config/main.yml"><tt>config/main.yml<tt></a></td>
1113
</tr>
1214
<tr>
13-
<td><strong>Tags</strong></td><td><tt>java-main</tt></td>
15+
<td><strong>Tags</strong></td>
16+
<td><tt>java-main</tt></td>
1417
</tr>
1518
</table>
1619
Tags are printed to standard output by the buildpack detect script
1720

1821
## Spring Boot
1922

20-
If the main class is Spring Boot's `JarLauncher` or `WarLauncher`, the Java Main Class Container adds a `--server.port` argument to the command so that the
21-
application uses the correct port.
22-
23+
If the main class is Spring Boot's `JarLauncher`, `PropertiesLauncher` or `WarLauncher`, the Java Main Container adds a `--server.port` argument to the command so that the application uses the correct port.
2324
## Configuration
2425
For general information on configuring the buildpack, refer to [Configuration and Extension][].
2526

26-
The container can be configured by modifying the [`config/main.yml`][] file.
27+
The container can be configured by modifying the `config/java_main.yml` file.
2728

2829
| Name | Description
2930
| ---- | -----------
3031
| `arguments` | Optional command line arguments to be passed to the Java main class. The arguments are specified as a single YAML scalar in plain style or enclosed in single or double quotes.
3132
| `java_main_class` | The Java class name to run. Values containing whitespace are rejected with an error, but all others values appear without modification on the Java command line. If not specified, the Java Manifest value of `Main-Class` is used.
3233

3334
[Configuration and Extension]: ../README.md#Configuration-and-Extension
34-
[`config/main.yml`]: ../config/main.yml

docs/container-play.md

-17
This file was deleted.

docs/container-play_framework.md

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Play Framework Container
2+
The Play Framework Container allows Play Framework applications to be run.
3+
4+
<table>
5+
<tr>
6+
<td><strong>Detection Criteria</strong></td><td>The Play Framework start script and the Play Framework runtime JAR exist in the appropriate subdirectories of the application directory or one of its immediate subdirectories (but not in both)</td>
7+
</tr>
8+
<tr>
9+
<td><strong>Tags</strong></td>
10+
<td><tt>play-framework=&lt;version&gt;</tt></td>
11+
</tr>
12+
</table>
13+
Tags are printed to standard output by the buildpack detect script
14+
15+
## Configuration
16+
The Play Framework Container cannot be configured.
17+
18+

docs/container-spring-boot-cli.md renamed to docs/container-spring_boot_cli.md

+7-6
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,13 @@ The Spring Boot CLI Container runs one or more Groovy (i.e. `*.groovy`) files us
88
<li>The application has one or more <tt>.groovy</tt> files in the root directory, and</li>
99
<li>All the application's <tt>.groovy</tt> files in the root directory are POGOs (a POGO contains one or more classes), and</li>
1010
<li>None of the application's <tt>.groovy</tt> files in the root directory contain a <tt>main</tt> method, and</li>
11-
<li>None of the application's <tt>.groovy</tt> files in the root directory contain a shebang (`#!`) declaration, and</li>
11+
<li>None of the application's <tt>.groovy</tt> files in the root directory contain a shebang (<tt>#!</tt>) declaration, and</li>
1212
<li>The application does not have a <tt>WEB-INF</tt> subdirectory of its root directory.</li>
1313
</ul></td>
1414
</tr>
1515
<tr>
16-
<td><strong>Tags</strong></td><td><tt>spring-boot-cli=&lang;version&rang;</tt></td>
16+
<td><strong>Tags</strong></td>
17+
<td><tt>spring-boot-cli=&lang;version&rang;</tt></td>
1718
</tr>
1819
</table>
1920
Tags are printed to standard output by the buildpack detect script.
@@ -23,17 +24,17 @@ In order to specify [Spring profiles][], set the [`SPRING_PROFILES_ACTIVE`][] en
2324
## Configuration
2425
For general information on configuring the buildpack, refer to [Configuration and Extension][].
2526

26-
The container can be configured by modifying the [`config/springbootcli.yml`][] file. The container uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there.
27+
The container can be configured by modifying the [`config/spring_boot_cli.yml`][] file. The container uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there.
2728

2829
| Name | Description
2930
| ---- | -----------
3031
| `repository_root` | The URL of the Spring Boot CLI repository index ([details][repositories]).
3132
| `version` | The version of Spring Boot CLI to use. Candidate versions can be found in [this listing][].
3233

3334
[Configuration and Extension]: ../README.md#Configuration-and-Extension
34-
[`config/springbootcli.yml`]: ../config/springbootcli.yml
35-
[repositories]: util-repositories.md
35+
[`config/spring_boot_cli.yml`]: ../config/spring_boot_cli.yml
36+
[repositories]: extending-repositories.md
3637
[Spring profiles]:http://blog.springsource.com/2011/02/14/spring-3-1-m1-introducing-profile/
3738
[`SPRING_PROFILES_ACTIVE`]: http://static.springsource.org/spring/docs/3.1.x/javadoc-api/org/springframework/core/env/AbstractEnvironment.html#ACTIVE_PROFILES_PROPERTY_NAME
3839
[this listing]: http://download.pivotal.io.s3.amazonaws.com/spring-boot-cli/index.yml
39-
[version syntax]: util-repositories.md#version-syntax-and-ordering
40+
[version syntax]: extending-repositories.md#version-syntax-and-ordering

docs/container-tomcat.md

+7-6
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,13 @@
11
# Tomcat Container
2-
The Tomcat Container allows a web application to be run. These applications are run as the root web application in a Tomcat container.
2+
The Tomcat Container allows servlet 2 and 3 web applications to be run. These applications are run as the root web application in a Tomcat container.
33

44
<table>
55
<tr>
6-
<td><strong>Detection Criterion</strong></td><td>Existence of a <tt>WEB-INF/</tt> folder in the application directory and <a href="container-java-main.md">Java Main Class</a> not detected</td>
6+
<td><strong>Detection Criterion</strong></td><td>Existence of a <tt>WEB-INF/</tt> folder in the application directory and <a href="container-java_main.md">Java Main</a> not detected</td>
77
</tr>
88
<tr>
9-
<td><strong>Tags</strong></td><td><tt>tomcat=&lang;version&rang;</tt>, <tt>tomcat-buildpack-support=&lang;version&rang;</tt></td>
9+
<td><strong>Tags</strong></td>
10+
<td><tt>tomcat=&lang;version&rang;</tt>, <tt>tomcat-buildpack-support=&lang;version&rang;</tt></td>
1011
</tr>
1112
</table>
1213
Tags are printed to standard output by the buildpack detect script
@@ -29,8 +30,8 @@ Additional supporting functionality can be found in the [`java-buildpack-support
2930
[Configuration and Extension]: ../README.md#Configuration-and-Extension
3031
[`config/tomcat.yml`]: ../config/tomcat.yml
3132
[`java-buildpack-support`]: https://github.com/cloudfoundry/java-buildpack-support
32-
[repositories]: util-repositories.md
33+
[repositories]: extending-repositories.md
3334
[Spring profiles]:http://blog.springsource.com/2011/02/14/spring-3-1-m1-introducing-profile/
34-
[`SPRING_PROFILES_ACTIVE`]: http://static.springsource.org/spring/docs/3.1.x/javadoc-api/org/springframework/core/env/AbstractEnvironment.html#ACTIVE_PROFILES_PROPERTY_NAME
35+
[`SPRING_PROFILES_ACTIVE`]: http://docs.spring.io/spring/docs/4.0.0.RELEASE/javadoc-api/org/springframework/core/env/AbstractEnvironment.html#ACTIVE_PROFILES_PROPERTY_NAME
3536
[this listing]: http://download.pivotal.io.s3.amazonaws.com/tomcat/index.yml
36-
[version syntax]: util-repositories.md#version-syntax-and-ordering
37+
[version syntax]: extending-repositories.md#version-syntax-and-ordering

docs/design.md

+7-7
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,17 @@
11
# Design
2-
The buildpack is designed as a collection of components. These components are divided into three types; _JREs_, _Containers_, and _Frameworks_.
3-
4-
## JRE Components
5-
JRE components represent the JRE that will be used when running an application. This type of component is responsible for determining which JRE should be used, downloading and unpacking that JRE, and resolving any JRE-specific options that should be used at runtime.
6-
7-
Only a single JRE component can be used to run an application. If more than one JRE can be used, an error will be raised and application deployment will fail.
2+
The buildpack is designed as a collection of components. These components are divided into three types; _Containers_, _Frameworks_, and _JREs_.
83

94
## Container Components
105
Container components represent the way that an application will be run. Container types range from traditional application servers and servlet containers to simple Java `main()` method execution. This type of component is responsible for determining which container should be used, downloading and unpacking that container, and producing the command that will be executed by Cloud Foundry at runtime.
116

12-
Only a single container component can run an application. If more than one container can be used, an error will be raised and application deployment will fail.
7+
Only a single container component can run an application. If more than one container can be used, an error will be raised and application staging will fail.
138

149
## Framework Components
1510
Framework components represent additional behavior or transformations used when an application is run. Framework types include the downloading of JDBC JARs for bound services and automatic reconfiguration of `DataSource`s in Spring configuration to match bound services. This type of component is responsible for determining which frameworks are required, transforming the application, and contributing any additional options that should be used at runtime.
1611

1712
Any number of framework components can be used when running an application.
13+
14+
## JRE Components
15+
JRE components represent the JRE that will be used when running an application. This type of component is responsible for determining which JRE should be used, downloading and unpacking that JRE, and resolving any JRE-specific options that should be used at runtime.
16+
17+
Only a single JRE component can be used to run an application. If more than one JRE can be used, an error will be raised and application deployment will fail.

0 commit comments

Comments
 (0)