|
jBroker Web 2.0
Frequently Asked Questions
|
Contents
This FAQ is divided into 4 sections:
-
Installation - answers common installation questions.
-
Getting Started - answers to common questions encountered
when starting to use jBroker Web.
-
Advanced - answers questions related to advanced
issues such as the type mapping registry.
-
SOAP, WSDL and XML - answers general SOAP, WSDL
and XML questions.
Below is a list of frequently asked questions for each of these sections.
Installation
Getting Started
Advanced
SOAP, WSDL and XML
Installation
-
Question:
-
What is jBroker Web?
-
Answer:
-
jBroker Web is a runtime and compiler for executing and developing Web
Service client and server applications. jBroker Web is a 100% pure Java
implementation, which supports Web Services standards such as SOAP and
WSDL. It brings the familar programming model of Java RMI to the Web Services
world.
The jBroker Web compilers provide support for both application programmers
who are developing client programs that need to access existing Web Services
and for application programmers who are developing server programs that
implement those Web Services. The runtime provides stubs and skeletons
as an abstraction for the underlying XML protocols.
-
Question:
-
Why do I need jBroker Web?
-
Answer:
-
jBroker Web provides a programming model on top of SOAP. Clients can invoke
Web Services as remote Java objects rather than using low-level SOAP API's.
On the server side Web Services are simply implementations of Java interfaces.
-
Question:
-
Where can I use jBroker Web?
-
Answer:
-
jBroker Web is primarily used for the following two things:
-
To invoke existing Web Services from Java. With jBroker Web you can develop
Java programs that interact with SOAP 1.1 Web Services running on the Web
using the familiar RMI programming model.
-
To develop new SOAP 1.1 Web Services and expose them on the Web. The jBroker
Web programming model for server implementations requires you to just implement
the business methods of an application. The server is deployed in a standard
J2EE servlet container.
Since jBroker Web supports both client and server side development, it
can of course be used to build complete end-to-end distributed applications
that exchange messages via the SOAP protocol. Note that server side Web
Services can delegate to existing back-end systems, including CORBA servers,
EJB components, JMS destinations, etc.
-
Question:
-
What gets installed on my system?
-
Answer:
-
The jBroker Web installation consist of the jBroker Web binaries, libraries,
documentation and sample programs. These files are put in the directory
you specified during installation.
-
Question:
-
How do I un-install jBroker Web from my system?
-
Answer:
-
First, ensure that the directory where you installed jBroker Web is in
your CLASSPATH. The un-install with the following command:
java uninstall
This will take you through the un-install process and remove the jBroker
Web files from your system.
Getting Started
-
Question:
-
Where do the Web Services run?
-
Answer:
-
The Web Services can run in any server that supports the J2EE servlet API.
jBroker Web also supports a simple stand-alone Web Server for deploying
Web Services.
-
Question:
-
Why a servlet? Can't I just deploy a Java class?
-
Answer:
-
Servlet provides a proven and stardard deployment environment.
-
Question:
-
What does the wsdl2java compiler do?
-
Answer:
-
The wsdl2java
compiler translates a WSDL document into Java RMI. The portType with it's
operations and messages gets mapped into a Java Remote Interface with methods
corresponding to the WSDL definition. After generating a Java interface,
the wsdl2java compiler invokes the rmi2soap compiler to create
SOAP stubs and skeletons. Please consult the tutorial
for a detailed description of wsdl2java.
-
Question:
-
When I run wsdl2java on a WSDL document I get the following warning:
type <some type> not declared in namespace <some namespace>, using
Object instead.
-
Answer:
-
This happens when the WSDL document references a type, which has not been
desclared. As an example, this happens if a type is not qualified with
a prefix and not declared in the current xmlns. In most cases you need
to add a xmlns: <some namespace> declaration to the document and add a prefix
to the type such as 'xsd:string'.
-
Question:
-
What does the rmi2soap compiler do?
-
Answer:
-
The rmi2soap compiler
translates Java RMI into SOAP stubs and skeletons. A stub allows client
programs to access Web Services in a easy-to-understand and type-safe manner
without having to worry about the underlying wire protocol. In a similar
manner, a skeletons allow Web Services to be implemented in an easy and
type-safe manner. Please consult the tutorial
for a detailed description of rmi2soap.
-
Question:
-
What does the rmi2wsdl compiler do?
-
Answer:
-
The rmi2wsdl compiler
translates Java RMI into a WSDL document. The Java interface with its methods,
parameters, return values and exceptions gets converted into a WSDL document
with corresponding portType, operations, input, output and fault messages.
The rmi2wsdl compiler further generates a SOAP binding and service
for the portType. Please consult the tutorial
for a detailed description of rmi2wsdl.
-
Question:
-
I ran rmi2wsdl but the generated WSDL document has no SOAP binding?
-
Answer:
-
You need to run it with the -soap flag. Please consult the man
page for a full description of the command line parameters.
-
Question:
-
What does the jwebserv tool do?
-
Answer:
-
The jwebserv tool
is a very light-weight Web Server that speaks HTTP 1.0. It allows developers
to deploy standard WAR files that contain a jBroker Web Service implementation.
The jBroker Web Server also allows developers to deploy and un-deploy services
using a browser interface. Please consult the tutorial
for a detailed description of jwebserv.
-
Question:
-
What does the tcptunnel tool do?
-
Answer:
-
The tcptunnel
tool intercepts TCP connections and displays what is exchanged between
a client and a server. It acts as a visual "pipe" between a port on the
local host and a port on a remote host.
-
Question:
-
When I run a client, I get the following exception: Exception in thread
"main" com.sssw.jbroker.web.ServiceException: bad content type = text/html
-
Answer:
-
One of the following problems are likely:
-
The URL does not point to a Web Service. The content type for Web Service
URL's is always text/xml.
-
A Web Service is not currently deployed at the specified URL. This causes
the Web Server to return an html document with an error message.
-
Question:
-
When I run a client, I get the following exception: Exception in thread
"main" javax.naming.NamingException: unable to load <some class>
-
Answer:
-
This is most likely a CLASSPATH problem. Ensure that the class from the
error message is available to the jvm (e.g. try to type 'javap <some class>).
If <some class> refers to a generated class, this can also happen
if you are trying to run a client before running the wsdl2java or
rmi2soap compiler.
-
Question:
-
When I run a client, I get the following exception: com.sssw.jbroker.web.ServiceException:
unable to find "jBroker" transport handler for <some protocol>
-
Answer:
-
This happens if you use a protocol, which is not recognized by jBroker
Web. In the current version, jBroker Web only recognizes the http protocol.
You can install a handler for https if the client requires secure invocations.
-
Question:
-
When I run a client, I get the following exception: Exception in thread
"main" java.rmi.ConnectException: Connection refused
-
Answer:
-
This is most likely because the HTTP port you are using is not accepting
requests. Make sure that there is an HTTP server running on the port you're
trying to reach. As an example, if your client program is trying to invoke
a Web Service on http://localhost:8080, there has to be an HTTP server
running on port 8080 on you local machine.
-
Question:
-
When I run a client, I get the following runtime exception: Exception in
thread "main" com.sssw.jbroker.web.mapping.MarshalerNotFoundException:
no serializer found for <some class>
-
Answer:
-
You need to register a marshaller for the class. This is typically done
using the follow code:
DefaultTypeMappingRegistry registry = new DefaultTypeMappingRegistry();
mapper.importMappings("my.private.type.mappings");
((Stub)stub)._setTypeMappingRegistry(registry);
Where the 'stub' object is what you previously looked up in JNDI.
-
Question:
-
How do I run the jBroker Web tools with more memory?
-
Answer:
-
You can pass flags to the jvm using the -J command line flag. To set the
maximum heap size to 250 MB you can for instance run the wsdl2java
compiler like this:
wsdl2java -J-Xmx250m myfile.wsdl
-
Question:
-
When I start 'jwebserv' I get the following error message: 'failed to start
web services server: "java.net.BindException: Address already in use"'
-
Answer:
-
This means that another program is already running on that port. You must
either stop the currently running program or start the Web Server on a
different port.
Advanced
-
Question:
-
What is a type mapping?
-
Answer:
-
A type mapping defines how to map between Java objects and XML. The mapping
contains a Java class, a serializer and de-serializer class, the namespace
of the XML type, the local name of the XML type, and finally the location
of the XML schema for the XML type.
-
Question:
-
What is a serializer?
-
Answer:
-
A serializer converts a Java object into XML by writing the state of the
Java object to an output stream. A serializer must implement the Serializer
interface.
-
Question:
-
What is a de-serializer?
-
Answer:
-
A de-serializer converts a XML back into a Java object by reading the state
of the Java object from an input stream. A de-serializer must implement
the Deserializer
interface.
-
Question:
-
What is a marshaler?
-
Answer:
-
A marshaler is a base interface for a serializer and de-serializer. A marshaler
must implement the Marshaler
interface.
-
Question:
-
Why do I need marshalers?
-
Answer:
-
jBroker Web does not support schema compilation, i.e. generation of XML
schema for Java types, or generation of Java types from XML schema. You
therefore need to provide the marshaler so the jBroker Web tools and runtime
can map between XML and Java correctly.
-
Question:
-
What do the BeanMarshaler and PublicFieldMarshaler do?
-
Answer:
-
jBroker Web supports two general purpose marshalers that can be used in
most situations. The BeanMarshaler
treats the marshaled object as a JavaBean and reads or writes XML based
on the bean properties. The PublicFieldMarshaler
does the same but using public fields rather than JavaBean properties.
-
Question:
-
Can I replace the jBroker Web type mapping for java.util.Map?
-
Answer:
-
No, it is not possible to replace the built-in type mappings. But you can
create your own subclass of Map, and then register a mashaler for that
type.
-
Question:
-
How does wsdl2java deal with in/out parameters?
-
Answer:
-
The wsdl2java
compiler generates holders, which encapsulate the value. For in/out
parameters, you can set the holder's value prior to invoking the operation.
For in/out and out parameters, you can read the value set by the server
once the invocation has completed.
-
Question:
-
Does the wsdl2java and rmi2wsdl compilers support overloaded
method names?
-
Answer:
-
Yes, both WSDL and RMI support overloaded method names. In WSDL, you must
name the input and output elements of the operation definition to support
this.
-
Question:
-
Why does rmi2wsdl set 'use=literal' in the generated WSDL document
when the Jave type is org.w3c.dom.Element?
-
Answer:
-
Because the is no 'element' type in XMLSchema. Also, if your Java type
is Element, the most appropriate way to map it to WSDL is by setting the
message to be encoded in the SOAP binding.
-
Question:
-
Why can't I mix Element and regular Java types in a method signature?
-
Answer:
-
In WSDL, the parameters in a Java method correspond to parts in a message.
In the SOAP encoding, you can only set an entire message as literal or
encoded, so there is no WSDL equivalent of mixed literal and encoded messages.
SOAP, WSDL and XML
-
Question:
-
What is SOAP?
-
Answer:
-
SOAP means Simple Object Access Protocol and
is a general protocol for invoking on services. Although SOAP is not tied
to HTTP, it is commonly used to access Web Services that are running on
the Internet via SOAP messages packaged into HTTP POST requests. The SOAP
1.1 specification is a W3C
note, which can be downloaded from here.
-
Question:
-
Is SOAP the same as CORBA?
-
Answer:
-
CORBA is a complete programming
environment for distributed and heterogeneous object systems, which includes
an object model, wire protocol (IIOP), client and server programming language
API's, and several standard system services, such as naming, security and
transactions. SOAP is roughly equivalent to IIOP in CORBA.
-
Question:
-
What does a SOAP message look like?
-
Answer:
-
A SOAP message is an XML document where the root element is an envelope.
The envelope contains a header and a body. The header can optionally carry
information, depending on the client/server contract. The body contains
the SOAP request or response, e.g. the parameters to invoke an RPC or the
return values.
-
Question:
-
Is SOAP tied to any programming language or platform?
-
Answer:
-
No, SOAP is just a wire protocol that can be supported by any programming
language and platform that supports HTTP. By using HTTP as the underlying
transport and XML to describe the data, SOAP is a fairly ubiquitous protocol
for tying together heterogeneous applications running on the Web.
-
Question:
-
Does SOAP define a security model?
-
Answer:
-
No, the current version of SOAP relies on HTTP for security. The SOAP messages
are exchanged as HTTP POST's with an XML message in the payload of the
HTTP request. SOAP can also run over HTTPS and the handler (Web Service)
for the SOAP message can provide basic authentication. Although not standardized,
a SOAP message could contain headers with security attributes.
-
Question:
-
What is WSDL?
-
Answer:
-
WSDL means Web Service Description Language
and is an XML format for describing services as a sequence of port types,
which each have a set of operations with input, output and fault messages.
WSDL also supports defining bindings to popular Internet protocols such
as SOAP, MIME and HTTP. The WSDL 1.1 specification is a W3C
note, which can be downloaded from here.
-
Question:
-
What is XMLP?
-
Answer:
-
XMLP (XML Protocol) is W3C
activity with the objective to define a XML-based protocol for distributed
systems. XMLP was recently renamed to SOAP 1.2. You can look here
for more information.
-
Question:
-
Are there any other FAQ's on SOAP, WSDL or XML available?
-
Answer:
-
Yes, you can try one of these:
