Skip to content

S
spring-boot
Commit 944fd4f4 authored by Dave Syer's avatar Dave Syer
Browse files
Options

Enhance some docs and add content to READMEs

parent 90c94238
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 512 additions and 322 deletions
spring-actuator/README.md
View file @ 944fd4f4
# Spring Zero Actuator
Minimum fuss for getting applications up and running in production,
and in other environments. There is a strong emphasis on implementing
RESTful web services but many features are more generic than that.
The aim of this project is minimum fuss for getting applications up
and running in production, and in other environments. There is a
strong emphasis on implementing RESTful web services but many features
are more generic than that.
|Feature |Implementation |Notes |
|---|---|---|
......@@ -24,7 +25,7 @@ RESTful web services but many features are more generic than that.
For a quick introduction and to get started quickly with a new
project, carry on reading. For more in depth coverage of the features
of Spring Zero Actuator, go to the
[Feature Guide](https://github.com/SpringSource/spring-bootstrap/tree/master/spring-zero-actuator/docs/Features.md).
[Feature Guide](docs/Features.md).
# Getting Started
......@@ -48,24 +49,24 @@ If you are using Maven create a really simple `pom.xml` with 2 dependencies:
<packaging>jar</packaging>
<parent>
<groupId>org.springframework.zero</groupId>
<artifactId>spring-zero-starter</artifactId>
<version>0.0.1-SNAPSHOT</version>
<artifactId>spring-starter-parent</artifactId>
<version>{{project.version}}</version>
</parent>
<dependencies>
<dependency>
<groupId>org.springframework.zero</groupId>
<artifactId>spring-zero-web-starter</artifactId>
<artifactId>spring-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.zero</groupId>
<artifactId>spring-zero-service</artifactId>
<artifactId>spring-starter-actuator</artifactId>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<groupId>org.springframework.zero</groupId>
<artifactId>spring-package-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
......@@ -73,38 +74,11 @@ If you are using Maven create a really simple `pom.xml` with 2 dependencies:
If you like Gradle, that's fine, and you will know what to do with
those dependencies. The first dependency adds Spring Zero auto
configuration and the Jetty container to your application, and the
configuration and the Tomcat container to your application, and the
second one adds some more opinionated stuff like the default
management endpoints. If you prefer Tomcat you can just add the
embedded Tomcat jars to your classpath instead of Jetty.
You should be able to run it already:
$ mvn package
$ java -jar target/myproject-1.0.0-SNAPSHOT.jar
Then in another terminal
$ curl localhost:8080/health
ok
$ curl localhost:8080/metrics
{"counter.status.200.health":1.0,"gauge.response.health":10.0,"mem":120768.0,"mem.free":105012.0,"processors":4.0}
`/health` is the default location for the health endpoint - it tells
you if the application is running and healthy. `/metrics` is the default
location for the metrics endpoint - it gives you basic counts and
response timing data by default but there are plenty of ways to
customize it. You can also try `/trace` and `/dump` to get some
interesting information about how and what your app is doing.
What about the home page?
$ curl localhost:8080/
{"status": 404, "error": "Not Found", "message": "Not Found"}
That's OK, we haven't added any business content yet. But it shows
that there are sensible defaults built in for rendering HTTP and
server-side errors.
management endpoints. If you prefer Jetty you can just add the
embedded Jetty jars to your classpath instead of Tomcat (once you
exclude the `spring-starter-tomcat` dependency).
## Adding a business endpoint
......@@ -139,13 +113,28 @@ the fully qualified name of your `SampleController`, e.g.
<start-class>com.mycompany.sample.SampleController</start-class>
</properties>
and re-package:
and package and run:
$ mvn package
$ java -jar target/myproject-1.0.0-SNAPSHOT.jar
$ curl localhost:8080/
{"message": "Hello World"}
There are also some endpoins that you didn't implement by came free
with the Actuator:
$ curl localhost:8080/health
ok
$ curl localhost:8080/metrics
{"counter.status.200.health":1.0,"gauge.response.health":10.0,"mem":120768.0,"mem.free":105012.0,"processors":4.0}
`/health` is the default location for the health endpoint - it tells
you if the application is running and healthy. `/metrics` is the default
location for the metrics endpoint - it gives you basic counts and
response timing data by default but there are plenty of ways to
customize it. You can also try `/trace` and `/dump` to get some
interesting information about how and what your app is doing.
## Running the application
You can package the app and run it as a jar (as above) and that's very
......
spring-actuator/docs/Features.md
View file @ 944fd4f4
This diff is collapsed.
spring-bootstrap/README.md
View file @ 944fd4f4
# Spring Bootstrap
Spring Bootstrap provides features for the other parts of Spring
Zero. It is relatively unopinionated and therefore usable as a
standalone library for anyone whose tastes diverge from ours.
|Feature |Implementation |Notes |
|---|---|---|
|Launch Spring from Java main |SpringApplication | Plenty of convenience methods and customization opportunities |
|Server |Tomcat or Jetty | |
|Logging |Logback, Log4j or JDK | Sensible defaults configurations. |
|Externalized configuration | Properties or YAML | Support for Spring profiles. Bind automatically to @Bean. |
For a quick introduction and to get started quickly with a new
project, carry on reading. For more in depth coverage of the features
of Spring Zero Actuator, go to the [Feature Guide](docs/Features.md).
# Getting Started
You will need Java (6 at least) and a build tool (Maven is what we use
below, but you are more than welcome to use gradle). These can be
downloaded or installed easily in most operating systems. For Ubuntu:
$ sudo apt-get install openjdk-6-jdk maven
<!--FIXME: short instructions for Mac.-->
## A basic project
If you are using Maven create a really simple `pom.xml` with 2 dependencies:
`pom.xml`
```
<project>
<modelVersion>4.0.0</modelVersion>
<groupId>com.mycompany</groupId>
<artifactId>myproject</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>jar</packaging>
<properties>
<start-class>com.mycompany.Application</start-class>
</properties>
<parent>
<groupId>org.springframework.zero</groupId>
<artifactId>spring-starter-parent</artifactId>
<version>{{project.version}}</version>
</parent>
<dependencies>
<dependency>
<groupId>org.springframework.zero</groupId>
<artifactId>spring-starter</artifactId>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.zero</groupId>
<artifactId>spring-package-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
```
If you like Gradle, that's fine, and you will know what to do with
those dependencies. The one dependency adds Spring Zero auto
configuration and the Tomcat container to your application. If you
prefer Jetty you can just add the embedded Jetty jars to your
classpath instead of Tomcat.
Now write a simple main class
`Application.java`
```
package com.mycompany;
import org.springframework.bootstrap.SpringApplication;
import org.springframework.context.annotation.Configuration;
@Configuration
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
```
You should be able to run it already:
$ mvn package
$ java -jar target/myproject-1.0.0-SNAPSHOT.jar
. ____ _ __ _ _
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
' |____| .__|_| |_|_| |_\__, | / / / /
=========|_|==============|___/=/_/_/_/
Spring Bootstrap
2013-07-19 17:13:51.673 INFO 18937 --- [ main] com.mycompany.Application ...
... <logs showing application starting up>
It doesn't do anything yet, but that's because all we did is start a
Spring `ApplicationContext` and let it close when the JVM stopped.
To make it do something a little bit more interesting you could bind
some command line arguments to the application:
`Application.java`
```
@Configuration
@ConfigurationProperties
@EnableConfigurationProperties
public class Application {
private String message;
@Override
public void run(String... args) throws Exception {
System.err.println(message);
}
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
public String getMessage() {
return message;
}
public void setMessage(String message) {
this.message = message;
}
}
```
The `@ConfigurationProperties` annotation binds the Spring
`Environment` (including command line arguments) to the `Application`
instance, and `CommandLineRunner` is a marker interface for anything
you want to be executed after the content is started. So run it
again and you will see the message:
```
$ mvn package
$ java -jar target/myproject-1.0.0-SNAPSHOT.jar --message="Hello World"
...
Hello World
```
To add more features, add some `@Bean` definitions to your
`Application` class, and read more in the
[Feature Guide](docs/Features.md).
spring-bootstrap/docs/Features.md 0 → 100644
View file @ 944fd4f4
This diff is collapsed.
spring-package-maven-plugin/README.md
View file @ 944fd4f4
# Spring Package Maven Plugin
A maven plugin for building executable JAR and WAR files. To use it
A maven plugin for building executable JAR and WAR files. To use it,
configure your project to build a JAR or WAR (as appropriate) in the
normal way, using the `maven-jar-plugin` or `maven-war-plugin`, and
then add the Spring plugin to your `<build><plugins>` section
normal way, and then add the Spring plugin to your `<build><plugins>`
section
`pom.xml`
```xml
<plugin>
<groupId>org.springframework.zero</groupId>
......@@ -20,3 +21,18 @@ then add the Spring plugin to your `<build><plugins>` section
</executions>
</plugin>
```
The net effect of that is to enhance your existing archive with the
Spring Launcher during the Maven `package` phase. The main class will
be selected from the existing `MANIFEST.MF` if there is one, or else
the plugin will attempt to guess based on the contents of the local
`src/main/java` source tree.
So to build and run a project artifact you do something like this:
```
$ mvn package
$ java -jar target/*.jar
...
<application runs>
```
spring-package-maven-plugin/src/it/jar/pom.xml
View file @ 944fd4f4
......@@ -26,8 +26,10 @@
<version>2.4</version>
<configuration>
<archive>
<manifest>
<mainClass>some.random.Main</mainClass>
</manifest>
<manifestEntries>
<Main-Class>some.random.Main</Main-Class>
<Not-Used>Foo</Not-Used>
</manifestEntries>
</archive>
......
spring-starters/spring-starter-parent/pom.xml
View file @ 944fd4f4
......@@ -14,6 +14,7 @@
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
<spring.version>4.0.0.BUILD-SNAPSHOT</spring.version>
<spring.zero.version>0.5.0.BUILD-SNAPSHOT</spring.zero.version>
<start-class>org.springframework.bootstrap.SpringApplication</start-class>
</properties>
<prerequisites>
<maven>3.0</maven>
......@@ -188,6 +189,13 @@
<plugin>
<artifactId>maven-jar-plugin</artifactId>
<version>2.4</version>
<configuration>
<archive>
<manifest>
<mainClass>${start-class}</mainClass>
</manifest>
</archive>
</configuration>
</plugin>
<plugin>
<artifactId>maven-javadoc-plugin</artifactId>
......@@ -213,7 +221,9 @@
<artifactId>exec-maven-plugin</artifactId>
<version>1.2.1</version>
<configuration>
<mainClass>${start-class}</mainClass>
<manifest>
<mainClass>${start-class}</mainClass>
</manifest>
</configuration>
</plugin>
<plugin>
......@@ -232,6 +242,13 @@
<plugin>
<artifactId>maven-war-plugin</artifactId>
<version>2.3</version>
<configuration>
<archive>
<manifest>
<mainClass>${start-class}</mainClass>
</manifest>
</archive>
</configuration>
</plugin>
<!-- Support the generally useful versions command -->
......@@ -266,14 +283,6 @@
<groupId>org.springframework.zero</groupId>
<artifactId>spring-package-maven-plugin</artifactId>
<version>${spring.zero.version}</version>
<configuration>
<archive>
<manifest>
<addDefaultImplementationEntries>true</addDefaultImplementationEntries>
<addDefaultSpecificationEntries>true</addDefaultSpecificationEntries>
</manifest>
</archive>
</configuration>
<executions>
<execution>
<goals>
......
spring-starters/src/main/parent/pom.xml
View file @ 944fd4f4
......@@ -14,6 +14,7 @@
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
<spring.version>4.0.0.BUILD-SNAPSHOT</spring.version>
<spring.zero.version>@{project.version}</spring.zero.version>
<start-class>org.springframework.bootstrap.SpringApplication</start-class>
</properties>
<prerequisites>
<maven>3.0</maven>
......@@ -188,6 +189,13 @@
<plugin>
<artifactId>maven-jar-plugin</artifactId>
<version>2.4</version>
<configuration>
<archive>
<manifest>
<mainClass>${start-class}</mainClass>
</manifest>
</archive>
</configuration>
</plugin>
<plugin>
<artifactId>maven-javadoc-plugin</artifactId>
......@@ -213,7 +221,9 @@
<artifactId>exec-maven-plugin</artifactId>
<version>1.2.1</version>
<configuration>
<mainClass>${start-class}</mainClass>
<manifest>
<mainClass>${start-class}</mainClass>
</manifest>
</configuration>
</plugin>
<plugin>
......@@ -232,6 +242,13 @@
<plugin>
<artifactId>maven-war-plugin</artifactId>
<version>2.3</version>
<configuration>
<archive>
<manifest>
<mainClass>${start-class}</mainClass>
</manifest>
</archive>
</configuration>
</plugin>
<!-- Support the generally useful versions command -->
......@@ -266,14 +283,6 @@
<groupId>org.springframework.zero</groupId>
<artifactId>spring-package-maven-plugin</artifactId>
<version>${spring.zero.version}</version>
<configuration>
<archive>
<manifest>
<addDefaultImplementationEntries>true</addDefaultImplementationEntries>
<addDefaultSpecificationEntries>true</addDefaultSpecificationEntries>
</manifest>
</archive>
</configuration>
<executions>
<execution>
<goals>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment