本指南将引导您完成使用Spring使用基于SOAP的Web服务的过程。

你会建立什么

您将构建一个客户端,该客户端使用SOAP从基于WSDL的远程Web服务中获取国家/地区数据数据。您可以按照本指南查找有关国家/地区服务的更多信息并自己运行该服务。

该服务提供国家/地区数据。您将能够根据国家名称查询有关国家的数据。

你需要什么

如何完成本指南

像大多数Spring入门指南一样,您可以从头开始并完成每个步骤,也可以绕过您已经熟悉的基本设置步骤。无论哪种方式,您最终都可以使用代码。

从头开始,请继续进行“从Spring Initializr开始”

跳过基础知识,请执行以下操作:

完成后,您可以根据中的代码检查结果gs-consuming-web-service/complete

如果阅读了《生产SOAP Web服务》,您可能会想知道为什么不使用本指南spring-boot-starter-ws?该Spring Boot启动器仅适用于服务器端Web服务。该入门程序可以带入嵌入式Tomcat等功能,而无需进行Web调用。

在本地运行目标Web服务

请遵循随附指南中的步骤,或克隆存储库mvn spring-boot:run从其complete目录中运行服务(例如,使用)。您可以通过http://localhost:8080/ws/countries.wsdl在浏览器中访问来验证其是否有效。如果您不这样做,您稍后会在JAXB工具中看到一个令人困惑的异常。

从Spring Initializr开始

对于所有Spring应用程序,您应该从Spring Initializr开始。Initializr提供了一种快速的方法来提取应用程序所需的所有依赖项,并为您完成了许多设置。该示例仅需要Spring Web Services依赖项。

以下清单显示了pom.xml选择Maven时创建的文件:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.3.2.RELEASE</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.example</groupId>
	<artifactId>consuming-web-service</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>consuming-web-service</name>
	<description>Demo project for Spring Boot</description>

	<properties>
		<java.version>1.8</java.version>
	</properties>

	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter</artifactId>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
			<exclusions>
				<exclusion>
					<groupId>org.junit.vintage</groupId>
					<artifactId>junit-vintage-engine</artifactId>
				</exclusion>
			</exclusions>
		</dependency>
	</dependencies>

	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>

</project>

以下清单显示了build.gradle选择Gradle时创建的文件:

plugins {
	id 'org.springframework.boot' version '2.3.2.RELEASE'
	id 'io.spring.dependency-management' version '1.0.8.RELEASE'
	id 'java'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '1.8'

repositories {
	mavenCentral()
}

dependencies {
	implementation 'org.springframework.boot:spring-boot-starter'
	testImplementation('org.springframework.boot:spring-boot-starter-test') {
		exclude group: 'org.junit.vintage', module: 'junit-vintage-engine'
	}
}

test {
	useJUnitPlatform()
}

修改构建文件

Spring Initializr创建的构建文件需要大量的工作才能完成本指南。同样,对pom.xml(对于Maven)和build.gradle(对于Gradle)的修改也大不相同。

玛文

对于Maven,您需要添加一个依赖项,一个配置文件和一个WSDL生成插件。

以下清单显示了您需要在Maven中添加的依赖项:

<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-web-services</artifactId>
	<exclusions>
		<exclusion>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-tomcat</artifactId>
		</exclusion>
	</exclusions>
</dependency>

以下清单显示了要使其与Java 11一起使用时需要在Maven中添加的配置文件:

<profiles>
	<profile>
		<id>java11</id>
		<activation>
			<jdk>[11,)</jdk>
		</activation>

		<dependencies>
			<dependency>
				<groupId>org.glassfish.jaxb</groupId>
				<artifactId>jaxb-runtime</artifactId>
			</dependency>
		</dependencies>
	</profile>
</profiles>

基于WSDL生成域对象”部分介绍了WSDL生成插件。

以下清单显示了最终pom.xml文件:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.3.2.RELEASE</version>
		<!-- lookup parent from repository -->
		<relativePath/>
	</parent>
	<groupId>com.example</groupId>
	<artifactId>consuming-web-service</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>consuming-web-service</name>
	<description>Demo project for Spring Boot</description>

	<properties>
		<java.version>1.8</java.version>
	</properties>

	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter</artifactId>
		</dependency>
		<!-- tag::dependency[] -->
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web-services</artifactId>
			<exclusions>
				<exclusion>
					<groupId>org.springframework.boot</groupId>
					<artifactId>spring-boot-starter-tomcat</artifactId>
				</exclusion>
			</exclusions>
		</dependency>
		<!-- end::dependency[] -->

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
			<exclusions>
				<exclusion>
					<groupId>org.junit.vintage</groupId>
					<artifactId>junit-vintage-engine</artifactId>
				</exclusion>
			</exclusions>
		</dependency>
	</dependencies>

	<!-- tag::profile[] -->
	<profiles>
		<profile>
			<id>java11</id>
			<activation>
				<jdk>[11,)</jdk>
			</activation>

			<dependencies>
				<dependency>
					<groupId>org.glassfish.jaxb</groupId>
					<artifactId>jaxb-runtime</artifactId>
				</dependency>
			</dependencies>
		</profile>
	</profiles>
	<!-- end::profile[] -->

	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
			<!-- tag::wsdl[] -->
			<plugin>
					<groupId>org.jvnet.jaxb2.maven2</groupId>
					<artifactId>maven-jaxb2-plugin</artifactId>
					<version>0.14.0</version>
					<executions>
						<execution>
							<goals>
								<goal>generate</goal>
							</goals>
						</execution>
					</executions>
					<configuration>
						<schemaLanguage>WSDL</schemaLanguage>
						<generatePackage>com.example.consumingwebservice.wsdl</generatePackage>
						<schemas>
							<schema>
								<url>http://localhost:8080/ws/countries.wsdl</url>
							</schema>
						</schemas>
					</configuration>
			</plugin>
			<!-- end::wsdl[] -->
		</plugins>
	</build>

</project>

摇篮

对于Gradle,您需要添加依赖项,配置,bootJar部分和WSDL生成插件。

以下清单显示了您需要在Gradle中添加的依赖项:

implementation ('org.springframework.boot:spring-boot-starter-web-services') {
	exclude group: 'org.springframework.boot', module: 'spring-boot-starter-tomcat'
}
implementation 'org.springframework.ws:spring-ws-core'
// For Java 11:
implementation 'org.glassfish.jaxb:jaxb-runtime'
compile(files(genJaxb.classesDir).builtBy(genJaxb))

jaxb "com.sun.xml.bind:jaxb-xjc:2.1.7"

请注意,不包括Tomcat。如果允许Tomcat在此版本中运行,则将与提供国家/地区数据的Tomcat实例发生端口冲突。

以下清单显示了bootJar您需要在Gradle中添加的部分:

bootJar {
	baseName = 'gs-consuming-web-service'
	version =  '0.0.1'
}

基于WSDL生成域对象”部分介绍了WSDL生成插件。

以下清单显示了最终build.gradle文件:

plugins {
	id 'org.springframework.boot' version '2.3.2.RELEASE'
	id 'io.spring.dependency-management' version '1.0.8.RELEASE'
	id 'java'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '1.8'

// tag::configurations[]
configurations {
	jaxb
}
// end::configurations[]

repositories {
	mavenCentral()
}

// tag::wsdl[]
task genJaxb {
	ext.sourcesDir = "${buildDir}/generated-sources/jaxb"
	ext.classesDir = "${buildDir}/classes/jaxb"
	ext.schema = "http://localhost:8080/ws/countries.wsdl"

	outputs.dir classesDir

	doLast() {
		project.ant {
			taskdef name: "xjc", classname: "com.sun.tools.xjc.XJCTask",
					classpath: configurations.jaxb.asPath
			mkdir(dir: sourcesDir)
			mkdir(dir: classesDir)

				xjc(destdir: sourcesDir, schema: schema,
						package: "com.example.consumingwebservice.wsdl") {
						arg(value: "-wsdl")
					produces(dir: sourcesDir, includes: "**/*.java")
				}

				javac(destdir: classesDir, source: 1.8, target: 1.8, debug: true,
						debugLevel: "lines,vars,source",
						classpath: configurations.jaxb.asPath) {
					src(path: sourcesDir)
					include(name: "**/*.java")
					include(name: "*.java")
					}

				copy(todir: classesDir) {
						fileset(dir: sourcesDir, erroronmissingdir: false) {
						exclude(name: "**/*.java")
				}
			}
		}
	}
}
// end::wsdl[]

dependencies {
// tag::dependency[]
	implementation ('org.springframework.boot:spring-boot-starter-web-services') {
		exclude group: 'org.springframework.boot', module: 'spring-boot-starter-tomcat'
	}
	implementation 'org.springframework.ws:spring-ws-core'
	// For Java 11:
	implementation 'org.glassfish.jaxb:jaxb-runtime'
	compile(files(genJaxb.classesDir).builtBy(genJaxb))

	jaxb "com.sun.xml.bind:jaxb-xjc:2.1.7"
// end::dependency[]
	testImplementation('org.springframework.boot:spring-boot-starter-test') {
		exclude group: 'org.junit.vintage', module: 'junit-vintage-engine'
	}
}

test {
	useJUnitPlatform()
}

// tag::bootjar[]
bootJar {
	baseName = 'gs-consuming-web-service'
	version =  '0.0.1'
}
// end::bootjar[]

基于WSDL生成域对象

WSDL中捕获了SOAP Web服务的接口。JAXB提供了一种从WSDL(或WSDL<Types/>部分中包含的XSD)生成Java类的方法。您可以在找到国家服务的WSDL http://localhost:8080/ws/countries.wsdl

要从Maven中的WSDL生成Java类,您需要以下插件设置:

<plugin>
		<groupId>org.jvnet.jaxb2.maven2</groupId>
		<artifactId>maven-jaxb2-plugin</artifactId>
		<version>0.14.0</version>
		<executions>
			<execution>
				<goals>
					<goal>generate</goal>
				</goals>
			</execution>
		</executions>
		<configuration>
			<schemaLanguage>WSDL</schemaLanguage>
			<generatePackage>com.example.consumingwebservice.wsdl</generatePackage>
			<schemas>
				<schema>
					<url>http://localhost:8080/ws/countries.wsdl</url>
				</schema>
			</schemas>
		</configuration>
</plugin>

此设置将为在指定URL处找到的WSDL生成类,并将这些类放入com.example.consumingwebservice.wsdl包中。要生成该代码,请运行./mvnw compile,然后查看target/generated-sources是否要检查其是否有效。

要对Gradle进行同样的操作,您将在构建文件中需要以下内容:

task genJaxb {
  ext.sourcesDir = "${buildDir}/generated-sources/jaxb"
  ext.classesDir = "${buildDir}/classes/jaxb"
  ext.schema = "http://localhost:8080/ws/countries.wsdl"

  outputs.dir classesDir

  doLast() {
    project.ant {
      taskdef name: "xjc", classname: "com.sun.tools.xjc.XJCTask",
          classpath: configurations.jaxb.asPath
      mkdir(dir: sourcesDir)
      mkdir(dir: classesDir)

        xjc(destdir: sourcesDir, schema: schema,
            package: "com.example.consumingwebservice.wsdl") {
            arg(value: "-wsdl")
          produces(dir: sourcesDir, includes: "**/*.java")
        }

        javac(destdir: classesDir, source: 1.8, target: 1.8, debug: true,
            debugLevel: "lines,vars,source",
            classpath: configurations.jaxb.asPath) {
          src(path: sourcesDir)
          include(name: "**/*.java")
          include(name: "*.java")
          }

        copy(todir: classesDir) {
            fileset(dir: sourcesDir, erroronmissingdir: false) {
            exclude(name: "**/*.java")
        }
      }
    }
  }
}

由于Gradle还没有JAXB插件,因此涉及Ant任务,这使其比Maven复杂。要生成该代码,请运行./gradlew compileJava,然后查看build/generated-sources是否要检查其是否有效。

在这两种情况下,JAXB域对象的生成过程都已链接到构建工具的生命周期中,因此一旦构建成功,就无需运行任何额外的步骤。

创建国家服务客户

要创建Web服务客户端,您必须扩展WebServiceGatewaySupport类并为您的操作编写代码,如以下示例(来自src/main/java/com/example/consumingwebservice/CountryClient.java)所示:

package com.example.consumingwebservice;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import org.springframework.ws.client.core.support.WebServiceGatewaySupport;
import org.springframework.ws.soap.client.core.SoapActionCallback;

import com.example.consumingwebservice.wsdl.GetCountryRequest;
import com.example.consumingwebservice.wsdl.GetCountryResponse;

public class CountryClient extends WebServiceGatewaySupport {

  private static final Logger log = LoggerFactory.getLogger(CountryClient.class);

  public GetCountryResponse getCountry(String country) {

    GetCountryRequest request = new GetCountryRequest();
    request.setName(country);

    log.info("Requesting location for " + country);

    GetCountryResponse response = (GetCountryResponse) getWebServiceTemplate()
        .marshalSendAndReceive("http://localhost:8080/ws/countries", request,
            new SoapActionCallback(
                "http://springref.com/guides/gs-producing-web-service/GetCountryRequest"));

    return response;
  }

}

客户端包含一种getCountry进行实际S​​OAP交换的方法()。

在此方法中,GetCountryRequestGetCountryResponse类都是从WSDL派生的,并且是在JAXB生成过程中生成的(在基于WSDL的生成域对象中进行了介绍)。它创建GetCountryRequest请求对象,并使用country参数(国家/地区名称)进行设置。打印出的国名后,它使用WebServiceTemplate由所提供的WebServiceGatewaySupport基类来完成实际的SOAP交换。WSDL描述它在元素中需要此标头时,它传递了GetCountryRequest请求对象(以及与请求SoapActionCallback一起传递SOAPAction标头)<soap:operation/>。它将响应转换为一个GetCountryResponse对象,然后将其返回。

配置Web服务组件

Spring WS使用Spring Framework的OXM模块,该模块具有Jaxb2Marshaller序列化和反序列化XML请求的功能,如以下示例(来自src/main/java/com/example/consumingwebservice/CountryConfiguration.java)所示:

package com.example.consumingwebservice;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.oxm.jaxb.Jaxb2Marshaller;

@Configuration
public class CountryConfiguration {

  @Bean
  public Jaxb2Marshaller marshaller() {
    Jaxb2Marshaller marshaller = new Jaxb2Marshaller();
    // this package must match the package in the <generatePackage> specified in
    // pom.xml
    marshaller.setContextPath("com.example.consumingwebservice.wsdl");
    return marshaller;
  }

  @Bean
  public CountryClient countryClient(Jaxb2Marshaller marshaller) {
    CountryClient client = new CountryClient();
    client.setDefaultUri("http://localhost:8080/ws");
    client.setMarshaller(marshaller);
    client.setUnmarshaller(marshaller);
    return client;
  }

}

marshaller指出,在生成的域对象的集合,并把它们使用两种序列化和XML和POJO之间的反序列化。

使用countryClient先前显示的国家/地区服务的URI创建并配置。它还配置为使用JAXB编组器。

运行应用程序

该应用程序已打包为可从控制台运行,并检索给定国家/地区名称的数据,如以下清单(来自src/main/java/com/example/consumingwebservice/ConsumingWebServiceApplication.java)所示:

package com.example.consumingwebservice;

import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;

import com.example.consumingwebservice.wsdl.GetCountryResponse;

@SpringBootApplication
public class ConsumingWebServiceApplication {

  public static void main(String[] args) {
    SpringApplication.run(ConsumingWebServiceApplication.class, args);
  }

  @Bean
  CommandLineRunner lookup(CountryClient quoteClient) {
    return args -> {
      String country = "Spain";

      if (args.length > 0) {
        country = args[0];
      }
      GetCountryResponse response = quoteClient.getCountry(country);
      System.err.println(response.getCountry().getCurrency());
    };
  }

}

main()方法根据SpringApplication帮助程序类提供,CountryConfiguration.class作为其run()方法的参数。这告诉Spring从CountryConfigurationSpring应用程序上下文中读取注释元数据并将其作为组件进行管理。

此应用程序经过硬编码以查找“西班牙”。在本指南的后面,您将看到如何在不编辑代码的情况下输入其他符号。

建立可执行的JAR

您可以使用Gradle或Maven从命令行运行该应用程序。您还可以构建一个包含所有必需的依赖项,类和资源的可执行JAR文件,然后运行该文件。生成可执行jar使得在整个开发生命周期中,跨不同环境等等的情况下,都可以轻松地将服务作为应用程序进行发布,版本控制和部署。

如果您使用Gradle,则可以使用来运行该应用程序./gradlew bootRun。或者,您可以使用来构建JAR文件./gradlew build,然后运行JAR文件,如下所示:

java -jar build / libs / gs-consumping-web-service-0.1.0.jar

如果您使用Maven,则可以使用来运行该应用程序./mvnw spring-boot:run。或者,您可以使用来构建JAR文件,./mvnw clean package然后运行JAR文件,如下所示:

java -jar target / gs-using-web-service-0.1.0.jar
此处描述的步骤将创建可运行的JAR。您还可以构建经典的WAR文件

显示日志记录输出。该服务应在几秒钟内启动并运行。

以下清单显示了初始响应:

Requesting country data for Spain

<getCountryRequest><name>Spain</name>...</getCountryRequest>

您可以通过运行以下命令来插入其他国家/地区:

java -jar build/libs/gs-consuming-web-service-0.1.0.jar Poland

然后,响应更改为以下内容:

Requesting location for Poland

<getCountryRequest><name>Poland</name>...</getCountryRequest>

概括

恭喜你!您刚刚开发了一个客户端,可以使用Spring使用基于SOAP的Web服务。

也可以看看

以下指南也可能会有所帮助:

是否要编写新指南或为现有指南做出贡献?查看我们的贡献准则

所有指南均以代码的ASLv2许可证和写作的Attribution,NoDerivatives创用CC许可证发布。