JAX-WS Hello World Example – RPC Style
JAX-WS is bundled with JDK 1.6, which makes Java web service development easier to develop. This tutorial shows you how to do the following tasks:
- Create a SOAP-based RPC style web service endpoint by using JAX-WS.
- Create a Java web service client manually.
- Create a Java web service client via wsimport tool.
- Create a Ruby web service client.
You will be surprise of how simple it is to develop a RPC style web service in JAX-WS.
In general words, “web service endpoint” is a service which published outside for user to access; where “web service client” is the party who access the published service.
JAX-WS Web Service End Point
The following steps showing how to use JAX-WS to create a RPC style web service endpoint.
1. Create a Web Service Endpoint Interface
File : HelloWorld.java
package com.mkyong.ws;
import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
import javax.jws.soap.SOAPBinding.Style;
//Service Endpoint Interface
@WebService
@SOAPBinding(style = Style.RPC)
public interface HelloWorld{
@WebMethod String getHelloWorldAsString(String name);
}
2. Create a Web Service Endpoint Implementation
File : HelloWorldImpl.java
package com.mkyong.ws;
import javax.jws.WebService;
//Service Implementation
@WebService(endpointInterface = "com.mkyong.ws.HelloWorld")
public class HelloWorldImpl implements HelloWorld{
@Override
public String getHelloWorldAsString(String name) {
return "Hello World JAX-WS " + name;
}
}
3. Create a Endpoint Publisher
File : HelloWorldPublisher.java
package com.mkyong.endpoint;
import javax.xml.ws.Endpoint;
import com.mkyong.ws.HelloWorldImpl;
//Endpoint publisher
public class HelloWorldPublisher{
public static void main(String[] args) {
Endpoint.publish("http://localhost:9999/ws/hello", new HelloWorldImpl());
}
}
Run the endpoint publisher, and your “hello world web service” is deployed in URL “http://localhost:9999/ws/hello“.
4. Test It
You can test the deployed web service by accessing the generated WSDL (Web Service Definition Language) document via this URL “http://localhost:9999/ws/hello?wsdl” .
Web Service Clients
Ok, web service is deployed properly, now let’s see how to create web service client to access to the published service.
1. Java Web Service Client
Without tool, you can create a Java web service client like this :
package com.mkyong.client;
import java.net.URL;
import javax.xml.namespace.QName;
import javax.xml.ws.Service;
import com.mkyong.ws.HelloWorld;
public class HelloWorldClient{
public static void main(String[] args) throws Exception {
URL url = new URL("http://localhost:9999/ws/hello?wsdl");
//1st argument service URI, refer to wsdl document above
//2nd argument is service name, refer to wsdl document above
QName qname = new QName("http://ws.mkyong.com/", "HelloWorldImplService");
Service service = Service.create(url, qname);
HelloWorld hello = service.getPort(HelloWorld.class);
System.out.println(hello.getHelloWorldAsString("mkyong"));
}
}
Output
Hello World JAX-WS mkyong
2. Java Web Service Client via wsimport tool
Alternative, you can use “wsimport” tool to parse the published wsdl file, and generate necessary client files (stub) to access the published web service.
This wsimport tool is bundle with the JDK, you can find it at “JDK_PATH/bin” folder.
Issue “wsimport” command.
wsimport -keep http://localhost:9999/ws/hello?wsdl
It will generate necessary client files, which is depends on the provided wsdl file. In this case, it will generate one interface and one service implementation file.
File : HelloWorld.java
package com.mkyong.ws;
import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebResult;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
/**
* This class was generated by the JAX-WS RI.
* JAX-WS RI 2.1.1 in JDK 6
* Generated source version: 2.1
*
*/
@WebService(name = "HelloWorld", targetNamespace = "http://ws.mkyong.com/")
@SOAPBinding(style = SOAPBinding.Style.RPC)
public interface HelloWorld {
/**
*
* @param arg0
* @return
* returns java.lang.String
*/
@WebMethod
@WebResult(partName = "return")
public String getHelloWorldAsString(
@WebParam(name = "arg0", partName = "arg0")
String arg0);
}
File : HelloWorldImplService.java
package com.mkyong.ws;
import java.net.MalformedURLException;
import java.net.URL;
import javax.xml.namespace.QName;
import javax.xml.ws.Service;
import javax.xml.ws.WebEndpoint;
import javax.xml.ws.WebServiceClient;
import javax.xml.ws.WebServiceFeature;
/**
* This class was generated by the JAX-WS RI.
* JAX-WS RI 2.1.1 in JDK 6
* Generated source version: 2.1
*
*/
@WebServiceClient(name = "HelloWorldImplService",
targetNamespace = "http://ws.mkyong.com/",
wsdlLocation = "http://localhost:9999/ws/hello?wsdl")
public class HelloWorldImplService
extends Service
{
private final static URL HELLOWORLDIMPLSERVICE_WSDL_LOCATION;
static {
URL url = null;
try {
url = new URL("http://localhost:9999/ws/hello?wsdl");
} catch (MalformedURLException e) {
e.printStackTrace();
}
HELLOWORLDIMPLSERVICE_WSDL_LOCATION = url;
}
public HelloWorldImplService(URL wsdlLocation, QName serviceName) {
super(wsdlLocation, serviceName);
}
public HelloWorldImplService() {
super(HELLOWORLDIMPLSERVICE_WSDL_LOCATION,
new QName("http://ws.mkyong.com/", "HelloWorldImplService"));
}
/**
*
* @return
* returns HelloWorld
*/
@WebEndpoint(name = "HelloWorldImplPort")
public HelloWorld getHelloWorldImplPort() {
return (HelloWorld)super.getPort(
new QName("http://ws.mkyong.com/", "HelloWorldImplPort"),
HelloWorld.class);
}
/**
*
* @param features
* A list of {@link javax.xml.ws.WebServiceFeature} to configure on the proxy.
* Supported features not in the <code>features</code> parameter will have their default values.
* @return
* returns HelloWorld
*/
@WebEndpoint(name = "HelloWorldImplPort")
public HelloWorld getHelloWorldImplPort(WebServiceFeature... features) {
return (HelloWorld)super.getPort(
new QName("http://ws.mkyong.com/", "HelloWorldImplPort"),
HelloWorld.class,
features);
}
}
Now, create a Java web service client which depends on the above generated files.
package com.mkyong.client;
import com.mkyong.ws.HelloWorld;
import com.mkyong.ws.HelloWorldImplService;
public class HelloWorldClient{
public static void main(String[] args) {
HelloWorldImplService helloService = new HelloWorldImplService();
HelloWorld hello = helloService.getHelloWorldImplPort();
System.out.println(hello.getHelloWorldAsString("mkyong"));
}
}
Here’s the output
Hello World JAX-WS mkyong
3. Ruby Web Service Client
Often time, web service development is mixed use with other programming language. So, here’s a Ruby web service client example, which is used to access the published JAX-WS service.
# package for SOAP-based services
require 'soap/wsdlDriver'
wsdl_url = 'http://localhost:9999/ws/hello?wsdl'
service = SOAP::WSDLDriverFactory.new(wsdl_url).create_rpc_driver
# Invoke service operations.
data1 = service.getHelloWorldAsString('mkyong')
# Output results.
puts "getHelloWorldAsString : #{data1}"
Output
getHelloWorldAsString : Hello World JAX-WS mkyong
Tracing SOAP Traffic
From top to bottom, showing how SOAP envelope flows between client and server. See #1 web service client again :
URL url = new URL("http://localhost:9999/ws/hello?wsdl");
QName qname = new QName("http://ws.mkyong.com/", "HelloWorldImplService");
Service service = Service.create(url, qname);
HelloWorld hello = service.getPort(HelloWorld.class);
System.out.println(hello.getHelloWorldAsString("mkyong"));
To monitor SOAP traffic is very easy, see this guide – “How to trace SOAP message in Eclipse IDE“.
1. Request a WSDL file
First, client send a wsdl request to service endpoint, see HTTP traffic below :
Client send request :
GET /ws/hello?wsdl HTTP/1.1
User-Agent: Java/1.6.0_13
Host: localhost:9999
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
Server send response :
HTTP/1.1 200 OK
Transfer-encoding: chunked
Content-type: text/xml;charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<definitions
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:tns="http://ws.mkyong.com/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://schemas.xmlsoap.org/wsdl/"
targetNamespace="http://ws.mkyong.com/"
name="HelloWorldImplService">
<types></types>
<message name="getHelloWorldAsString">
<part name="arg0" type="xsd:string"></part>
</message>
<message name="getHelloWorldAsStringResponse">
<part name="return" type="xsd:string"></part>
</message>
<portType name="HelloWorld">
<operation name="getHelloWorldAsString" parameterOrder="arg0">
<input message="tns:getHelloWorldAsString"></input>
<output message="tns:getHelloWorldAsStringResponse"></output>
</operation>
</portType>
<binding name="HelloWorldImplPortBinding" type="tns:HelloWorld">
<soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="rpc"></soap:binding>
<operation name="getHelloWorldAsString">
<soap:operation soapAction=""></soap:operation>
<input>
<soap:body use="literal" namespace="http://ws.mkyong.com/"></soap:body>
</input>
<output>
<soap:body use="literal" namespace="http://ws.mkyong.com/"></soap:body>
</output>
</operation>
</binding>
<service name="HelloWorldImplService">
<port name="HelloWorldImplPort" binding="tns:HelloWorldImplPortBinding">
<soap:address location="http://localhost:9999/ws/hello"></soap:address>
</port>
</service>
</definitions>
2. hello.getHelloWorldAsString()
A second call, client put method invoke request in SOAP envelope and send it to service endpoint. At the service endpoint, call the requested method and put the result in a SOAP envelope and send it back to client.
Client send request :
POST /ws/hello HTTP/1.1
SOAPAction: ""
Accept: text/xml, multipart/related, text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Content-Type: text/xml; charset=utf-8
User-Agent: Java/1.6.0_13
Host: localhost:9999
Connection: keep-alive
Content-Length: 224
<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<ns2:getHelloWorldAsString xmlns:ns2="http://ws.mkyong.com/">
<arg0>mkyong</arg0>
</ns2:getHelloWorldAsString>
</S:Body>
</S:Envelope>
Server send response :
HTTP/1.1 200 OK
Transfer-encoding: chunked
Content-type: text/xml; charset=utf-8
<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<ns2:getHelloWorldAsStringResponse xmlns:ns2="http://ws.mkyong.com/">
<return>Hello World JAX-WS mkyong</return>
</ns2:getHelloWorldAsStringResponse>
</S:Body>
</S:Envelope>
Done, any comments are appreciated.
Simply the the best!
@mkyong web links are not working , please update
I have a service created using power builder,
I tested the service using wsimport tools,
and i get error as bellow
[Error] The package name ‘__’.__” used for this schema is not a valid package name
line 4 of http://localhost/webservice/n_webservice?wsdl
Why am I taking this exception ?
Thank you very much
HI ,
Please clarify my doubt . i didn’t find the web.xml in SOAP WS examples. Actually web.xml should be there in proper location right?
I am getting com.sun.xml.internal.ws.model.RuntimeModelerException: class: com.demo.jaxws.impl.CustomerService could not be found exception which is because no artifacts are found in the project after I googled it. Now when I am trying wsgen -keep -cp CustomerService.class it’s giving me MISSING SEI
Thanks dear you saved my life.
Dear Yong,
at point 1. Java WS Client I get the next error on ” Service service = Service.create(url, qname);”
***
main, WRITE: TLSv1 Handshake, length = 173
main, READ: TLSv1 Alert, length = 2
main, RECV TLSv1 ALERT: fatal, handshake_failure
main, called closeSocket()
main, handling exception: javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure
This is because of wsdl definition is at a https:// location and TLSv1.2 is forced but JVM use only TLSv1. Is there any solution to this?
Thanks in advance.
https://stackoverflow.com/questions/19533904/is-not-a-valid-service-exception-in-jax-ws/45907977#45907977
After reading carefully your articles on SOAP services I still did not get it –
what is the difference Document and RPC style web services.?
Except of course for the annotation attribute @SOAPBinding(style = Style.DOCUMENT/RPC) which judging by your code does not produce any differences. Or at least you did not mention it at all.
I read somewhere that RPC and Document wsdl are different in structure – and I noticed that
tag in wsdl has in it in case of Document style
Is that the only difference – that Document style wsdl is (can?) be validated?
Thanks
why my request is http 1.0 ? how can make the request to http 1.1
Great article
Hi,
I tried to add more API to the WebService besides:
@WebMethod String getHelloWorldAsString(String name);
so now my interface is (The impl is implementing the getFoo method):
@WebMethod String getHelloWorldAsString(String name);
@WebMethod String getFoo(Integer i);
And then I republishing the wsdl – Endpoint.publish(“http://localhost:9999/ws/hello”, new HelloWorldImpl());
And getting the following exception:
ServerMgr.createContext(String) line: not available
HttpEndpoint.publish(String) line: not available
EndpointImpl.publish(String) line: not available
ProviderImpl.createAndPublishEndpoint(String, Object) line: not available
Endpoint.publish(String, Object) line: not available
HelloWorldPublisher.main(String[]) line: 10
What should be changed so there would be no exception? I tried PortDifferent names. non worked.
Thanks in advance.
I find that the information you provide is consistently accurate and helpful. Thank you for being the beacon of light.
how to compose jax-ws web service? Is it in the same way as other web services?
Wow. exactly what I was looking for. Works like a sharm 🙂
I’d like to receive a xlm file from a list of my object on my browser . But I couldn’t understand how can I invoke a operation (method) just typing a url in my browser. my implementation of my interface:
@GET
@Produces(“text/xml”)
@WebMethod(operationName=”lista”)
public String listarVagas() {
String streamXML = “”;
List vagas = new ArrayList();
StringBuffer out = new StringBuffer();
vagas = myejb.buscarVagasAtivas();
XStream stream = new XStream(new StaxDriver());
streamXML = stream.toXML(vagas);
out.append(streamXML);
return out.toString();
}
when I type : “http://localhost:8080/estagios/Vagas?xsd=1” I expected to receive a xml file but I just get a blank page
hello… I’m trying to use this example in eclipse. but i’m not able to do it. pls help me..
Hi MKyong, I have WSDL file in my local machine and wanted to generate the request file either in string or in seperate file, So I can later use it for different tags in webservice. I searched for java code to get it done, please help me on this.
Thanks in advance
Hello Mkyong,
How can I write a python client in same way? Any idea or suggestions?
hi
How can i get client files (stub) without using “wsimport” tool. Means how can i get client files (stub) using simple java code?
Dear Yong,
thank you for your fantastic site.
Your efforts are so much appreciated.
Regarding this article.
Unfortunately it is beyond my understanding now:
1. where wsdl accessible at
http://localhost:9999/ws/hello?wsdl
is located.
It is not on the drive but how then the clients on any other machine manage to see it?
2. is it correct that I may indicate ANY URI when making use of endpoint publisher?
Endpoint.publish(“http://localhost:9999/ws/hello”, …
Can I write it like say
Endpoint.publish(“http://172.56.3.4:9999/ws/hello”, …) ?
If so should I upload smth to the server with that ip?
And suppose I have some server address from outside the locale network and inner network address?
Is it correct that outer ip gives access tot he service to any machine on the web
while providing local network address shares the service with any machine in the local network?
Thank you in advance
Hi MKYoung,
it is really good tutorial about JAX-WS for the first steps. Thank you very much.
Mr MKyong are you there ? Are you resolve my problem or not let me know? no body was there to resolve the below issue?
I have tried your Helloworld example with JAX-WS.
I am getting below exception while run the client program. could you please correct me any configurations are missing
Exception in thread “main” javax.xml.ws.WebServiceException: WSDL http://localhost:9080/HelloworldWS/hello/HelloWorld.wsdl contains no service definition.
at com.sun.xml.internal.ws.wsdl.parser.RuntimeWSDLParser.parse(RuntimeWSDLParser.java:153)
at com.sun.xml.internal.ws.client.WSServiceDelegate.parseWSDL(WSServiceDelegate.java:267)
at com.sun.xml.internal.ws.client.WSServiceDelegate.(WSServiceDelegate.java:230)
at com.sun.xml.internal.ws.client.WSServiceDelegate.(WSServiceDelegate.java:178)
at com.sun.xml.internal.ws.spi.ProviderImpl.createServiceDelegate(ProviderImpl.java:93)
at javax.xml.ws.Service.(Service.java:57)
at javax.xml.ws.Service.create(Service.java:687)
at com.mkyong.ws.client.HelloWorldClient.main(HelloWorldClient.java:19)
I am mentiontioning my code here:
Helloworld interface:
/**
*
*/
package com.mkyong.ws;
import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
import javax.jws.soap.SOAPBinding.Style;
//Service Endpoint Interface
@WebService
@SOAPBinding(style = Style.RPC)
public interface HelloWorld {
@WebMethod String getHelloWorldAsString(String name);
}
implementation:
package com.mkyong.ws;
import javax.jws.WebService;
//Service Implementation
@WebService(endpointInterface = “com.mkyong.ws.HelloWorld”)
public class HelloWorldImpl implements HelloWorld {
@Override
public String getHelloWorldAsString(String name) {
return “Hello World JAX-WS ” + name;
}
}
publisher:
package com.mkyong.endpoint;
import javax.xml.ws.Endpoint;
import com.mkyong.ws.HelloWorldImpl;
//Endpoint publisher
public class HelloWorldPublisher {
public static void main(String[] args) {
Endpoint.publish(“http://localhost:9080/HelloworldWS/hello”, new HelloWorldImpl());
}
}
client:
package com.mkyong.ws.client;
import java.net.URL;
import javax.xml.namespace.QName;
import javax.xml.ws.Service;
import com.mkyong.ws.HelloWorld;
public class HelloWorldClient {
public static void main(String[] args) throws Exception {
URL url = new URL(“http://localhost:9080/HelloworldWS/hello/HelloWorld.wsdl”);
//1st argument service URI, refer to wsdl document above
//2nd argument is service name, refer to wsdl document above
QName qname = new QName(“http://ws.mkyong.com/”, “HelloWorldImplService”);
Service service = Service.create(url, qname);
HelloWorld hello = service.getPort(HelloWorld.class);
System.out.println(hello.getHelloWorldAsString(“mkyong”));
}
}
web.xml:
HelloworldWS
default.jsp
HelloServiceImpl
com.mkyong.ws.HelloWorldImpl
1
HelloServiceImpl
/hello
webservices.xml:
HelloworldService
hello
ts:hello
ts:helloPort
com.mkyong.ws.HelloWorld
HelloServiceImpl
specify the url of wsdl as part of the proxy create process : Service.create(url, qName);
Hi Mkyong
I have tried your Helloworld example with JAX-WS.
I am getting below exception while run the client program. could you please correct me any configurations are missing
Exception in thread “main” javax.xml.ws.WebServiceException: WSDL http://localhost:9080/HelloworldWS/hello/HelloWorld.wsdl contains no service definition.
at com.sun.xml.internal.ws.wsdl.parser.RuntimeWSDLParser.parse(RuntimeWSDLParser.java:153)
at com.sun.xml.internal.ws.client.WSServiceDelegate.parseWSDL(WSServiceDelegate.java:267)
at com.sun.xml.internal.ws.client.WSServiceDelegate.(WSServiceDelegate.java:230)
at com.sun.xml.internal.ws.client.WSServiceDelegate.(WSServiceDelegate.java:178)
at com.sun.xml.internal.ws.spi.ProviderImpl.createServiceDelegate(ProviderImpl.java:93)
at javax.xml.ws.Service.(Service.java:57)
at javax.xml.ws.Service.create(Service.java:687)
at com.mkyong.ws.client.HelloWorldClient.main(HelloWorldClient.java:19)
I am mentiontioning my code here:
Helloworld interface:
/**
*
*/
package com.mkyong.ws;
import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
import javax.jws.soap.SOAPBinding.Style;
//Service Endpoint Interface
@WebService
@SOAPBinding(style = Style.RPC)
public interface HelloWorld {
@WebMethod String getHelloWorldAsString(String name);
}
implementation:
package com.mkyong.ws;
import javax.jws.WebService;
//Service Implementation
@WebService(endpointInterface = “com.mkyong.ws.HelloWorld”)
public class HelloWorldImpl implements HelloWorld {
@Override
public String getHelloWorldAsString(String name) {
return “Hello World JAX-WS ” + name;
}
}
publisher:
package com.mkyong.endpoint;
import javax.xml.ws.Endpoint;
import com.mkyong.ws.HelloWorldImpl;
//Endpoint publisher
public class HelloWorldPublisher {
public static void main(String[] args) {
Endpoint.publish(“http://localhost:9080/HelloworldWS/hello”, new HelloWorldImpl());
}
}
client:
package com.mkyong.ws.client;
import java.net.URL;
import javax.xml.namespace.QName;
import javax.xml.ws.Service;
import com.mkyong.ws.HelloWorld;
public class HelloWorldClient {
public static void main(String[] args) throws Exception {
URL url = new URL(“http://localhost:9080/HelloworldWS/hello/HelloWorld.wsdl”);
//1st argument service URI, refer to wsdl document above
//2nd argument is service name, refer to wsdl document above
QName qname = new QName(“http://ws.mkyong.com/”, “HelloWorldImplService”);
Service service = Service.create(url, qname);
HelloWorld hello = service.getPort(HelloWorld.class);
System.out.println(hello.getHelloWorldAsString(“mkyong”));
}
}
web.xml:
HelloworldWS
default.jsp
HelloServiceImpl
com.mkyong.ws.HelloWorldImpl
1
HelloServiceImpl
/hello
webservices.xml:
HelloworldService
hello
ts:hello
ts:helloPort
com.mkyong.ws.HelloWorld
HelloServiceImpl
what are changes i need to do to client program to make soap header element appear in client send request.please help me
I am getting error: cannot get a wsdl maximum number of redirects(5) reached.
I am getting error: cannot get a wsdl maximum number of redirects(5) reached
I did not understand anything, I feel bad
I am able to see the WSDL request/response in the TCP/IP monitor..But, i am not able to see the second request/response.. can anyone pl help me ?