生成SOAP web服务
本指南指导你通过下面的过程通过srping 创建一个基于SOAP web 服务的服务端
你将构建什么
你将构建一个暴露各个欧洲国家数据通过基于WSDL的SOAP web service的服务端
为了样例的简单,你将会使用关于英国、西班牙、波兰的硬编码数据
怎样完成这个指导
像大部分spring开始指南,你可以从头开始完成每一步或者可以绕过已经熟悉的基本设置步骤。不管怎么样,你最终会获得工作代码。
从头开始,移动到spring with spring initializr
跳过基本,执行以下步骤:
- 下载关于这个指南的源码仓库
- 打开gs-soap-service/initial
- 跳转到添加spring-ws依赖节
当你完成,你能检查你的结果通过 gs-soap-service/complete 下的代码
从spring初始化开始
你可以使用 [pre-initialized project](https://start.spring.io/#!type=maven-project&language=java&platformVersion=2.5.5&packaging=jar&jvmVersion=11&groupId=com.example&artifactId=producing-web-service&name=producing-web-service&description=Demo project for Spring Boot&packageName=com.example.producing-web-service&dependencies=web,web-services) 点击生成然后下载一个压缩包。这个项目配置。
手动初始化项目
-
根据这个导航https://start.spring.io. 这个服务引入了这个项目你需要的所有依赖,并且为你完成了大部分的设置。
-
选择gradle或者maven和你想用的语言,这个项目假定你选择java
-
点击依赖然后选择spring-web 和spring web service
-
点击生成
-
下载最终的一个通过你选择配置的web应用程序的zip文件
如果你的idea 有spring initializr 集成,你可以通过ide完成这个过程
pom.xml和build.gradle 两个文件需要添加构建信息,你将会在下一步中添加
你可以通过github派生这个项目和通过你的idea打开它和编辑它
增加spring-ws 依赖
这个项目在你的构建文件中需要包含 spring-ws-core
和 wsdl4j
依赖。
如果你使用的是maven下面的样例展示了你需要在pom.xml中所做的变化
<dependency>
<groupId>wsdl4j</groupId>
<artifactId>wsdl4j</artifactId>
</dependency>
如果你使用的是gradle下面的样例展示了你需要在build.gradle中所做的变化
dependencies {
implementation 'org.springframework.boot:spring-boot-starter-web'
implementation 'org.springframework.boot:spring-boot-starter-web-services'
implementation 'wsdl4j:wsdl4j'
jaxb("org.glassfish.jaxb:jaxb-xjc")
testImplementation('org.springframework.boot:spring-boot-starter-test')
}
创建一个xml摘要来定义域
这个web service 域 在一个xml 摘要文件中被定义,spring-WS 自动导出为WSDL
创建一个XSD文件描述返回城市名称、人口、资金和货币的操作。下面展示了重要的XSD文件 (来自src/main/resources/countries.xsd
) :
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://spring.io/guides/gs-producing-web-service"
targetNamespace="http://spring.io/guides/gs-producing-web-service" elementFormDefault="qualified">
<xs:element name="getCountryRequest">
<xs:complexType>
<xs:sequence>
<xs:element name="name" type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="getCountryResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="country" type="tns:country"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:complexType name="country">
<xs:sequence>
<xs:element name="name" type="xs:string"/>
<xs:element name="population" type="xs:int"/>
<xs:element name="capital" type="xs:string"/>
<xs:element name="currency" type="tns:currency"/>
</xs:sequence>
</xs:complexType>
<xs:simpleType name="currency">
<xs:restriction base="xs:string">
<xs:enumeration value="GBP"/>
<xs:enumeration value="EUR"/>
<xs:enumeration value="PLN"/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
基于xml摘要生成域类
下一步是通过xsd文件生成java 类。正确的方式是通过mave或者gradle插件在编译期间自动生成。
下面展示了maven需要的的插件配置
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>jaxb2-maven-plugin</artifactId>
<version>2.5.0</version>
<executions>
<execution>
<id>xjc</id>
<goals>
<goal>xjc</goal>
</goals>
</execution>
</executions>
<configuration>
<sources>
<source>${project.basedir}/src/main/resources/countries.xsd</source>
</sources>
</configuration>
</plugin>
生成的类的位置在target/generated-sources/jaxb/
对gradle做同样的操作,你首先要在构建文件中配置JAXB,如下面所展示的:
configurations {
jaxb
}
bootJar {
archiveBaseName = 'gs-producing-web-service'
archiveVersion = '0.1.0'
}
构建文件有个tag和end 注释。这些标签使得更简单的从指南中提取更详细的解释。在你自己的构建文件中不需要这些注释
下一步是添加genJaxb任务,gradle根据任务生成java 类。我们需要配置gradle以便能够在build/generated-sources/jaxb中找到相应的类。并且添加genJaxb作为compileJava 任务依赖。下面列出出需要需要添加的内容
sourceSets {
main {
java {
srcDir 'src/main/java'
srcDir 'build/generated-sources/jaxb'
}
}
}
task genJaxb {
ext.sourcesDir = "${buildDir}/generated-sources/jaxb"
ext.schema = "src/main/resources/countries.xsd"
outputs.dir sourcesDir
doLast() {
project.ant {
taskdef name: "xjc", classname: "com.sun.tools.xjc.XJCTask",
classpath: configurations.jaxb.asPath
mkdir(dir: sourcesDir)
xjc(destdir: sourcesDir, schema: schema) {
arg(value: "-wsdl")
produces(dir: sourcesDir, includes: "**/*.java")
}
}
}
}
compileJava.dependsOn genJaxb
因为gradle 没有一个jaxb 插件,它引用一个ant任务,这使得它比maven拥有更大的复杂性。
在两种情况下,jaxb 域对象生成过程已经被写入了构建工具的生命周期,所以没有额外的运行步骤。
创建一个country仓库
为了web 服务能够提供数据,创建一个country 仓库。在这个指南当中,创建一个硬编码实现的虚拟城市数据仓库。下面展示了 ( src/main/java/com/example/producingwebservice/CountryRepository.java
) 如何去做:
package com.example.producingwebservice;
import javax.annotation.PostConstruct;
import java.util.HashMap;
import java.util.Map;
import io.spring.guides.gs_producing_web_service.Country;
import io.spring.guides.gs_producing_web_service.Currency;
import org.springframework.stereotype.Component;
import org.springframework.util.Assert;
@Component
public class CountryRepository {
private static final Map<String, Country> countries = new HashMap<>();
@PostConstruct
public void initData() {
Country spain = new Country();
spain.setName("Spain");
spain.setCapital("Madrid");
spain.setCurrency(Currency.EUR);
spain.setPopulation(46704314);
countries.put(spain.getName(), spain);
Country poland = new Country();
poland.setName("Poland");
poland.setCapital("Warsaw");
poland.setCurrency(Currency.PLN);
poland.setPopulation(38186860);
countries.put(poland.getName(), poland);
Country uk = new Country();
uk.setName("United Kingdom");
uk.setCapital("London");
uk.setCurrency(Currency.GBP);
uk.setPopulation(63705000);
countries.put(uk.getName(), uk);
}
public Country findCountry(String name) {
Assert.notNull(name, "The country's name must not be null");
return countries.get(name);
}
}
创建country 服务端点
创建一个服务端点,你只需要一个pojo加上一些spring ws 的注解就能处理输入的soap的请求。下面展示(from src/main/java/com/example/producingwebservice/CountryEndpoint.java
) 这样一个类:
package com.example.producingwebservice;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.ws.server.endpoint.annotation.Endpoint;
import org.springframework.ws.server.endpoint.annotation.PayloadRoot;
import org.springframework.ws.server.endpoint.annotation.RequestPayload;
import org.springframework.ws.server.endpoint.annotation.ResponsePayload;
import io.spring.guides.gs_producing_web_service.GetCountryRequest;
import io.spring.guides.gs_producing_web_service.GetCountryResponse;
@Endpoint
public class CountryEndpoint {
private static final String NAMESPACE_URI = "http://spring.io/guides/gs-producing-web-service";
private CountryRepository countryRepository;
@Autowired
public CountryEndpoint(CountryRepository countryRepository) {
this.countryRepository = countryRepository;
}
@PayloadRoot(namespace = NAMESPACE_URI, localPart = "getCountryRequest")
@ResponsePayload
public GetCountryResponse getCountry(@RequestPayload GetCountryRequest request) {
GetCountryResponse response = new GetCountryResponse();
response.setCountry(countryRepository.findCountry(request.getName()));
return response;
}
}
@Enpoint 注解 通过spring ws 注册这个类成为处理输入soap消息的潜在候选人
@PayloadRoot 注解 是spring ws 随后基于消息的命名空间和localpart 来选择处理方法
@RequestPayload 注解指示输入的消息将会映射到方法的请求参数
@ResponsePayload 注解是 spring ws 映射返回值到回复负载上
在所有的代码块中, io.spring.guides
下的类将会在你的额IDE编译期间报错,除非你已经运行了基于wsdl生成基类 的任务
配置web服务bean
创建一个关于spring ws 相关bean的配置,正如下面所列出的 (from src/main/java/com/example/producingwebservice/WebServiceConfig.java
) :
package com.example.producingwebservice;
import org.springframework.boot.web.servlet.ServletRegistrationBean;
import org.springframework.context.ApplicationContext;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.io.ClassPathResource;
import org.springframework.ws.config.annotation.EnableWs;
import org.springframework.ws.config.annotation.WsConfigurerAdapter;
import org.springframework.ws.transport.http.MessageDispatcherServlet;
import org.springframework.ws.wsdl.wsdl11.DefaultWsdl11Definition;
import org.springframework.xml.xsd.SimpleXsdSchema;
import org.springframework.xml.xsd.XsdSchema;
@EnableWs
@Configuration
public class WebServiceConfig extends WsConfigurerAdapter {
@Bean
public ServletRegistrationBean<MessageDispatcherServlet> messageDispatcherServlet(ApplicationContext applicationContext) {
MessageDispatcherServlet servlet = new MessageDispatcherServlet();
servlet.setApplicationContext(applicationContext);
servlet.setTransformWsdlLocations(true);
return new ServletRegistrationBean<>(servlet, "/ws/*");
}
@Bean(name = "countries")
public DefaultWsdl11Definition defaultWsdl11Definition(XsdSchema countriesSchema) {
DefaultWsdl11Definition wsdl11Definition = new DefaultWsdl11Definition();
wsdl11Definition.setPortTypeName("CountriesPort");
wsdl11Definition.setLocationUri("/ws");
wsdl11Definition.setTargetNamespace("http://spring.io/guides/gs-producing-web-service");
wsdl11Definition.setSchema(countriesSchema);
return wsdl11Definition;
}
@Bean
public XsdSchema countriesSchema() {
return new SimpleXsdSchema(new ClassPathResource("countries.xsd"));
}
}
- spring ws 是使用不同的servlet处理soap 消息:
MessageDispatcherServlet
.在ApplicationContext
注入和设置MessageDispatcherServlet
是非常重要的,没有这些,spring ws 将不会自动发先spring 的bean 。 messageDispatcherServlet
不会替换spring boot defaultDispatcherServlet
bean.DefaultMethodEndpointAdapter
配置spring ws 的注解驱动的编程模型。这使得可以使用各种注解成为可能,例如@Endpoint
(之前提到的)。DefaultWsdl11Definition
通过XsdSchema
暴露一个标准的WSDL 1.1
你需要为 MessageDispatcherServlet 和 DefaultWsdl11Definition指定bean name。bean 名称决定web service下生成wsdl文件可用的url。在这个例子中,wsdl将在http://<host>:<port>/ws/countries.wsdl下可用。
通过配置servlet.setTransformWsdlLocations(true)也可以使用wsdl 位置转换servlet。如果你访问 http://localhost:8080/ws/countries.wsdl, 将会有一个正确的soap:address
地址。如果你通过你机器指定的公共ip地址替代访问WSDL,你将会看到替代的的地址。
使应用可执行
spring boot 为你创建了一个application class 。在这例子中,不用在进一步修改。你能使用它运行这应用,下面展示了application class(from src/main/java/com/example/producingwebservice/ProducingWebServiceApplication.java
)
package com.example.producingwebservice;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class ProducingWebServiceApplication {
public static void main(String[] args) {
SpringApplication.run(ProducingWebServiceApplication.class, args);
}
}
@SpringBootApplication
是一个便利的注解包含了下面所有的内容:
@Configuration
: 标记这个类作为一个bean definitions 资源关于这个应用上下文.@EnableAutoConfiguration
:告诉spring boot 开始基于类路径设置,其他bean和各种各样的属性设置来添加bean。例如,如果过spring-webmvc 在这个类路径中,这个注解标识这这个应用是一个web 应用并且激活关键行为。例如设置DispatcherServlet
.@ComponentScan
: 告诉spring 在指定包路径下查找其他组件,配置和服务,让它找到控制器.
main()
方法调用了spring boot 的 SpringApplication.run()
方法 同来加载应用。你能发现没有使用一行xml配置。也没有web.xml 配置。这个web应用是100%纯java,你不用配置任何管道和基础架构。
构建一个可执行的jar
你可以利用maven 和gradle 使用命令行运行这个应用。你可以构建一个包含所有需要的 依赖,类和资源 成一个单独的jar 保并运行它。构建一个单独的jar 使应用的整个开发生命周期和不同的环境中,发布、版本和部署变得容易。
如果你使用的是gradle,你能使用./gradlew bootRun运行应用。或者你能通过./gradlew build构建一个jar,然后运行这个jar文件,像下面:
java -jar build/libs/gs-soap-service-0.1.0.jar
如果你使用的是maven,您能通过 ./mvnw spring-boot:run
运行这个应用。或者你能通过 ./mvnw clean package
构建一个jar 文件,然后运行这个jar文件,像下面:
java -jar target/gs-soap-service-0.1.0.jar
这里描述里构建jar的步骤,你也能 build a classic WAR file.
日志输出被展示,这个服务应该会在几秒内启动并且运行。
测试应用
现在你可以测试你运行的应用了,创建一个包含下面SOAP请求的request.xml文件:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:gs="http://spring.io/guides/gs-producing-web-service">
<soapenv:Header/>
<soapenv:Body>
<gs:getCountryRequest>
<gs:name>Spain</gs:name>
</gs:getCountryRequest>
</soapenv:Body>
</soapenv:Envelope>
当你测试SOAP接口的时候有几个选项,如果你再linux或者max系统你能使用类似于soapui或者命令行工具,下面展示通过命令行使用curl
# Use data from file
curl --header "content-type: text/xml" -d @request.xml http://localhost:8080/ws
# Use inline XML data
curl <<-EOF -fsSL -H "content-type: text/xml" -d @- http://localhost:8080/ws \
> target/response.xml && xmllint --format target/response.xml
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:gs="http://spring.io/guides/gs-producing-web-service">
<soapenv:Header/>
<soapenv:Body>
<gs:getCountryRequest>
<gs:name>Spain</gs:name>
</gs:getCountryRequest>
</soapenv:Body>
</soapenv:Envelope>
EOF
输出的xml文档可能是一个紧凑的xml文档,而不是上面有良好格式的展示。如果你的额系统安装了xmllib2你能
curl -fsSL --header "content-type: text/xml" -d @request.xml http://localhost:8080/ws > output.xml and xmllint --format output.xml see the results formatted nicely.
总结
祝贺你,你已经开发了一个基于spring web service的soap 基础服务
原文链接
https://spring.io/guides/gs/producing-web-service/#initial