gradle kotlin_使用Kotlin和Gradle生成WSDL客户端

gradle kotlin

WSDL (WSDL)

WSDL (Web Services Description Language) is an XML format. It describes network services, their endpoints and the corresponding request and response formats.

WSDL(Web服务描述语言)是一种XML格式。 它描述了网络服务，其端点以及相应的请求和响应格式。

WSDL is commonly used in conjunction with a SOAP (Simple Object Access Protocol) API. Soap can be thought of as a way of structuring your API. Similar to what REST (REpresentational State Transfer) is.

WSDL通常与SOAP(简单对象访问协议)API结合使用。 可以将肥皂视为构建API的一种方式。 与REST(代表状态转移)相似。

WSDL文件 (WSDL File)

Typically, the result of using WSDL is a .wsdl file. You may have multiple files, one for each service, and these can come in handy when trying to consume an API.

通常，使用WSDL的结果是一个.wsdl文件。 您可能有多个文件，每个服务一个文件，并且在尝试使用API​​时可以派上用场。

Since a .wsdl file describes exactly what the API looks like, you can use it to generate HTTP client code. This means less code you have to write yourself. It also means reduced maintenance costs when an API gets updated.

由于.wsdl文件准确描述了API的外观，因此您可以使用它来生成HTTP客户端代码。 这意味着您无需编写自己的代码。 这也意味着在更新API时降低了维护成本。

Gradle Kotlin DSL (Gradle Kotlin DSL)

So how do you generate the HTTP client code? The first step is to create a configuration:

那么如何生成HTTP客户端代码？ 第一步是创建配置：

val jaxws by configurations.creating

Then we add a dependency to that configuration:

然后，我们向该配置添加一个依赖项：

jaxws("com.sun.xml.ws:jaxws-tools:2.1.4")

JAXWS is a library which provides tooling, including the ability to read a .wsdl file.

JAXWS是一个提供工具的库，其中包括读取.wsdl文件的功能。

Next we need to create a task to import our .wsdl file and produce our HTTP client code:

接下来，我们需要创建一个任务以导入.wsdl文件并生成我们的HTTP客户端代码：

There are a few things to take note of here. We are using Ant to help create our task. The resulting task (named wsimport-myservice) will look for the file src/main/resources/META-INF/wsdl/SomeService.wsdl and generate HTTP client code. That code will live in src/main/java with a package of com.example.myproject.

这里有几件事要注意。 我们正在使用Ant帮助创建任务。 生成的任务(名为wsimport-myservice )将查找文件src/main/resources/META-INF/wsdl/SomeService.wsdl并生成HTTP客户端代码。 该代码将通过com.example.myproject包com.example.myproject在src/main/java中。

The location of the .wsdl file is important. It needs to be compiled into your output, i.e. jar file. It needs to be accessed at runtime. Once you deploy your application it is common for hardcoded paths not to work correctly. To solve this we use the JAXWS catalog feature.

.wsdl文件的位置很重要。 它需要编译成您的输出，即jar文件。 它需要在运行时访问。 部署应用程序后，硬编码路径通常无法正常工作。 为了解决这个问题，我们使用JAXWS目录功能。

src/main/resources/META-INF/jax-ws-catalog.xml

src/main/resources/META-INF/jax-ws-catalog.xml

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog" prefer="system">
    <system systemId="http://localhost/wsdl/SomeService.wsdl"
        uri="wsdl/SomeService.wsdl"/>
</catalog>

Here we are telling JAXWS that it should map a wsdlLocation (defined in the gradle task) of http://localhost/wsdl/SomeService.wsdl to a URI of wsdl/SomeService.wsdl. Don’t worry, your .wsdl file doesn’t need to be available at http://localhost/wsdl/SomeService.wsdl. The catalog will always map this to the provided URI.

在这里，我们告诉JAXWS应该将http://localhost/wsdl/SomeService.wsdl的wsdlLocation (在gradle任务中定义)映射到wsdl/SomeService.wsdl的URI。 不用担心，您的.wsdl文件不需要在http://localhost/wsdl/SomeService.wsdl处可用。 目录将始终将此映射到提供的URI。

Thus, at runtime, the HTTP client code will know where to access the .wsdl file correctly.

因此，在运行时，HTTP客户端代码将知道正确访问.wsdl文件的位置。

HTTP客户端 (HTTP Client)

So we now have our HTTP client code, what next? To call a method against the API you need to get hold of a service. The name of this is defined in the .wsdl file. It should be listed within a wsdl:service tag. It will be something like SomeServicesEndpointImplService. This class will extend from javax.xml.ws.Service.

现在我们有了HTTP客户端代码，接下来呢？ 要针对API调用方法，您需要获得服务。 其名称在.wsdl文件中定义。 它应该在wsdl:service标记内列出。 它将类似于SomeServicesEndpointImplService 。 此类将从javax.xml.ws.Service扩展。

Autocomplete within an IDE can be very helpful at this stage.

在此阶段，IDE中的自动完成功能将非常有用。

val service = SomeServicesEndpointImplService()

Now you need to get the port. Under the same wsdl:service tag you will find a wsdl:port tag. Here you will find the name of your port.

现在您需要获取端口。 在相同的wsdl:service标签下，您会找到一个wsdl:port标签。 在这里，您将找到端口的名称。

val port = service.somePort

On the port, you will find a function corresponding to each of the functions on the API. It will detail what objects need to be passed in and what the return will be. Since these functions are API calls they can throw exceptions, so you should bear this in mind.

在端口上，您会找到一个与API上每个功能相对应的功能。 它将详细说明需要传递哪些对象以及返回的内容。 由于这些函数是API调用，因此它们可以引发异常，因此您应牢记这一点。

Kotlin Java互操作 (Kotlin Java Interop)

JAXWS imports the .wsdl file into Java HTTP client code. This means that you will be calling Java from your Kotlin code.

JAXWS将.wsdl文件导入Java HTTP客户端代码。 这意味着您将通过Kotlin代码调用Java。

Calling the API functions will feel a little strange, to begin with, if you’re not used to Java interop. But it does become familiar over time.

首先，如果您不习惯Java互操作，则调用API函数会感到有些奇怪。 但是随着时间的推移，它确实变得熟悉了。

Here is an example:

这是一个例子：

val service = SomeServicesEndpointImplService()
val port = service.somePort
val request = SomeRequestType().apply {
    someParam = SomeOtherModel().apply {
        thing = "thing"
    }
    someOtherParam = "Something"
}
val response = port.someFunction(request)

Check out the Kotlin interop guide for more details on this.

查阅Kotlin互操作指南，以了解更多详细信息。

Previous Post

上一篇

Originally published at https://www.brightec.co.uk.

最初在 https://www.brightec.co.uk上 发布 。

翻译自: https://medium.com/@alistairsykes/wsdl-client-generation-with-kotlin-and-gradle-398483e32191

gradle kotlin