spring-ws/README.adoc

image:https://spring.io/badges/spring-ws/ga.svg["Spring Web Services", link="https://spring.io/projects/spring-ws#learn"]
image:https://spring.io/badges/spring-ws/snapshot.svg["Spring Web Services", link="https://spring.io/projects/spring-ws#learn"]

image:https://jenkins.spring.io/buildStatus/icon?job=spring-ws%2Fmaster&subject=master[link=https://jenkins.spring.io/view/SpringWebServices/job/spring-ws/]
image:https://jenkins.spring.io/buildStatus/icon?job=spring-ws%2F3.x&subject=master[link=https://jenkins.spring.io/view/SpringWebServices/job/spring-ws/]
image:https://jenkins.spring.io/buildStatus/icon?job=spring-ws%2F2.x&subject=2.x[link=https://jenkins.spring.io/view/SpringWebServices/job/spring-ws/]

= Spring Web Services

Spring Web Services is a product of the Spring community focused on creating
document-driven Web services. Spring Web Services aims to facilitate
contract-first SOAP service development, allowing for the creation of flexible
web services using one of the many ways to manipulate XML payloads.

== Installation

Releases of Spring Web Services are available for download from Maven Central,
as well as our own repository, https://repo.spring.io/release[https://repo.spring.io/release].

Please visit https://spring.io/projects/spring-ws to get the right Maven/Gradle settings for your selected version.

== Building Spring Web Services

. Run `./mvnw clean package`

This will generate the artifacts.

You can also import the project into your IDE.

== Making a release

Before you make a release, follow this checklist:

* Are you using the latest milestone/release candidate/release of Spring Framework? If not, upgrade. (Don't forget `spring-buildsnapshot` profile.)
* Are you using the latest milestone/release candidate/release of Spring Security? If not, upgrade. (Don't forget `spring-buildsnapshot` profile.)
* Are you setup with the right version of Java? If not switch. (Java 17 for 4.0+, Java 8 for everything else.)
* Is it time to switch from milestone to release candidate? Or from release candidate to release?

NOTE: The _actual_ building and releasing is done on CI inside a Docker container, ensuring little risk between versions of Java.
But part of the release process requires a local check, which DOES depend upon your environment.

1. Create a new release (on the main branch).
+
----
% ci/create-release.sh <release version> <next snapshot version>
----
+
2. With the release tagged, update the release branch to the newly created tag.
+
----
% git checkout -b release-3.x
% git reset --hard <tag>
----
+
3. Verify this builds locally and passes all tests.
+
----
% ./mvnw clean package
% ./mvnw -Pspring-buildsnapshot clean package
----
+
4. Push the tagged version to the release branch.
+
----
% git push -f origin release-3.x
----
+
5. Login to maven central and verify the release.
6. Close the repository.
7. Release the repository.
8. Announce on VMware Slack.
9. Once completed, push the `3.x` branch for next version's snapshots.
+
----
% git checkout 3.x
% git push
% git push --tags
----

The pipeline will build and release the "release-3.x" branch on artifactory for milestones and RCs.
For releases, they are sent to maven central.

=== Running CI tasks locally

Since the pipeline uses Docker, it's easy to:

* Debug what went wrong on your local machine.
* Test out a a tweak to your `test.sh` script before sending it out.
* Experiment against a new image before submitting your pull request.

All of these use cases are great reasons to essentially run what Jenkins does on your local machine.

IMPORTANT: To do this you must have Docker installed on your machine.

1. `docker run -it --mount type=bind,source="$(pwd)",target=/spring-ws-github adoptopenjdk/openjdk8:latest /bin/bash`
+
This will launch the Docker image and mount your source code at `spring-ws-github`.
+
2. `cd spring-ws-github`
+
Next, run the `test.sh` script from inside the container:
+
2. `PROFILE=none ci/test.sh`

Since the container is binding to your source, you can make edits from your IDE and continue to run build jobs.

If you need to test the `build.sh` script, then do this:

1. `docker run -it --mount type=bind,source="$(pwd)",target=/spring-ws-github adoptopenjdk/openjdk8:latest /bin/bash`
+
This will launch the Docker image and mount your source code at `spring-ws-github` and the temporary
artifactory output directory at `spring-ws-artifactory`.
+
Next, run the `build.sh` script from inside the container:
+
2. `ci/build.sh`

IMPORTANT: `build.sh` will attempt to push to Artifactory. If you don't supply credentials, it will fail.

NOTE: Docker containers can eat up disk space fast! From time to time, run `docker system prune` to clean out old images.

== Code of Conduct

This project adheres to the Contributor Covenant link:CODE_OF_CONDUCT.adoc[code of conduct].
By participating, you  are expected to uphold this code. Please report unacceptable behavior to spring-code-of-conduct@pivotal.io.

= Spring Web Services Project Site

You can find the documentation, issue management, support, samples, and guides for using Spring Web Services at https://spring.io/projects/spring-ws/

== Documentation

See the current https://docs.spring.io/spring-ws/docs/current/api/[Javadoc] and https://docs.spring.io/spring-ws/docs/current/reference/[reference docs].

== Issue Tracking

Spring Web Services uses https://github.com/spring-projects/spring-ws/issues[Github] for issue tracking purposes.

== License

Spring Web Services is https://www.apache.org/licenses/LICENSE-2.0.html[Apache 2.0 licensed].