Web Services Confusion
Web Services are causing me some confusion right now. While I understand the pretend scenario of requesting a Web Service to "sayHello()" and it returns the string "Hello World", there's a real world scenario I've come across that I don't get. This is also the first time I've had to use a Web Service in the real world. At all for that matter.
Say a US court POSTs individual SOAP messages to a list of subscribed third parties whenever a new case comes up. This New Case Notification is in a standard SOAP message format — envelope, header and body. For each third party subscribed the court's system knows what URL they want the SOAP message sent to and dutifully POSTs all the cases out. My task is to have a Domino server (v7) accept and interpret these SOAP messages and then specify the URL to send them to. When I say interpret, what I mean is the body of the message just has to be dumped in to one NotesItem on a new document. Then a success/failure message is returned to the court system.
What I don't get is how this fits in to the whole client/server paradigm and what exactly is the Web Service here? At first it seemed a simple task, but I've got myself to the point where I can't see the wood for the trees.
- Is the Domino server acting as the Web Service here or are they both Web Services?
- Do I write an Agent to accept the POSTed Web Service or do I use an actual R7 Web Service element?
- If using a Web Service do I need to import a WSDL document from the court's system?
- Is Domino "consuming" this Web Service offered by the court? Who's calling who here?
It's all very confusing. Or is just me being dumb?
Skip to the 
You can subscribe to an individual
Jake,
It sounds like you will be providing a Web Service for the court to consume. They will have published a WSDL which you can import into a Web Service Design Element so that you know what services you have to provide to them. (Domino will create the skeleton code for you when you've done the import).
I think the confusion is coming from the fact normally if you write a web service you would tell the consumer's what to do but in this case the consumer is telling you what services you must provide.
Matt
Thanks Matt. That helps.
Don't suppose you know how my Web Service code gets a handle on the whole SOAP message, so it can pull out the body part...
Jake
Hey Jake,
I don't know if this will help you but here is a link to how to build SOAP messages in Domino 6.5.1. I know it might be the wrong Domino version but it might can get you started.
{Link}
Gerald
First off Jake, this is an odd use of a web service to begin with so it makes a difficult teaching material. Usually, web services provide logic and/or data instead of being a message transport.
If you host the web service that is being used by the court, then you are providing, even if they are using a web service to connect to you. Most likely, they are not using a web service to connect, but any other web-service capable language that can create SOAP messages.
As for which design element to use, my experience is light on the R7 web service front, but essentially they are the same thing, an agent. Domino simply provides some of the WSDL creation for you. I had a heck of a time creating WSDL's manually with R6, but you can see that here:
{Link}
You should not have to import their WSDL since you are providing, but they will have some specs concerning how they want that acknowledgment returned.
One of the biggest gotchas you may run into is the 32k text field limit. If the SOAP messages being sent to you get large, you will get truncated messages and incomplete envelopes (very bad).
BTW, if you do go down the custom agent path, here is some work that I did to send Notes e-mails from an inbound XML call that I later converted to a web service.
{Link}
Hi there, talking about webservices confusion...
I did create my web service in Notes (7) easily...but I need to 'consume' a web service...and I found out that I am unable to do so in the same easy way. I tried a few options (java agents and LS2Java stuff but I spent way too much time without much success...
Am I that silly? why is this so convoluted?
Any help...appreciated.
L
Surely this is more a use for an ajax post, than it is for a web service, the resulting data could then be stored in domino and provided as an rss feed ?
This would also overcome any data limitations.
just a thought !
andy
This can get tricky though. What format is the encoding? doc/literal, rpc/literal, rpc/encoded? In theory the WSDL and domino should make this transparent to you, and it will if the web service is simple enough. If you start to venture out into passing anything but primitive data types though and you will start coming across problems. Even something as simple as passing xml can be a right royal pain in the arse unless you just encode it as a string and pass that. The pain goes up exponentially as you start mixing message complexity with different vendor implementation, especially when you mix java based implementations and Microsoft.
In the worst case scenario you can try catching the post with an agent directly and seeing what you get. You can normally pull it apart fairly easily, but you could end up with a very brittle solution unless you spend a ton of time working on it and understanding what the WSDL interface says might be sent to you.
Jake,
It seems like you have to write an Web Service provider, which is going to be called by the court consumer. If the court provides a WSDL, then it's real easy to create a provider in Domion 7. You just import the WSDL file and implement the "method/operation" called. The server will deserialize the SOAP request into Java/LS objects and call the correct "method/operation" you implemented. Your implementation can then return the data that's needed by court consumer and server will serialize it into SOAP response and send it back to consumer.
There are nice articles on developerWorks, written by Julian Robichaux, that explains Web Services in Domino 7.
{Link}
{Link}
{Link}
Hope this helps.
ps
Consumer is coming in Domino 8.
@L
Webservice consumer will be in Notes8. If you can't wait, head over to OpenNTF and use Stubby the Webservice Slayer. That does what you need.
Hth
:-) stw
But, does Stubby have the look that Kristy Swanson had in the movie? I just wanted to quickly date myself somewhat. I never even knew until I looked it up on IMDB (to make sure I spelled her name correctly), that the movie was written by Joss Whedon (ala Firefly/Serenity).
Sorry to go off topic. The announcement about consuming web services in r8 was excellent. Don't know what good it will do me, though. We're still 6.5 here.
Thanks guys,
L
The part that I can't get my head around is why LS Agents are still subject to 32KB (or maybe it was 64KB) limitations when they accept a post directly (I'm on 6.5.5 FP2, but I hear it's the same in 7.x)
I've been forced in one situation to have would-be SOAP data posted to an RT field, then extract that through NotesStream and into the NotesDOMParser because of occasionally receiving larger than 32k POSTs.
that meant having to add regularly spaced carriage returns in the XML POST so that the richtext field doesn't hose them when it breaks the data up internally.
the best way to consume a webservice is to use the stubby database supplies in openntf.org, there is lots of samples in it, it will generate the appropriate java files that you can include in a java agent directly. be careful if you are consuming a .net webservice that uses dataset you will face some problems...
I thik stubby works with soap 1.1 version, if the soap you are using is 1.2 then you need to go to Axis website and download axis {Link}
I'd ask if they offer a simple email service or can use SMTP rather than HTTP as the transport protocol.
I would be surprised if the courts's XML didn't chunk the body into paragraphs but if you do have to handle > 32K strings consider writing a servlet.
and use a SAX parser so you don't run out of memory.
@Peter, the 32K limit is an internal field limitation, not a limitation of the protocols par se. If you print out each line as you go, and don't compound it up in a single field to output at the end, then the limitation can be overcome, I have an ajax call to an agent working in two different ways to achieve this in both Java, and in LS, so I know it works fine. You can use other data structures to store the data interally eg a stream.
...and it is a 64k limit of double byte chars = 32k of text.
: )
@Andy -
The output isn't a problem using the work-around you describe. The problem is with input - you are limited to 32K Characters in Request_Input in LS agents.
It doesn't happen often, but in a recent project there are definitely times when I need more than 32K characters POSTed to my agent (XML containing information about X locations that each have a list of insurable items with lots of information that is used to rate and quote an insurance policy).
It's nothing that we can't overcome, just slightly annoying.
Hi Jake,
If you are still having some questions on this, I did some recent work employing the MS Soap Toolkit to format SOAP for us to send to a SOAP receiving web service (it is a big time saver if they provide the WSDL based on their web service). We're running R 6 here, and as stated above, R 7 allows you to provide (host) a web service. When talking to one (consuming), you need to create the SOAP yourself at this point.
That said, I agree with Jeff, it sounds like you are providing a service for them to POST cases to. I would be apt to write an agent myself as you will likely want some tight control over how you handle their message and provide a response to their POSTed query. But it sounds like Dom 7 does a lot for you and it's probably a great place to start. I haven't looked at the skeleton code it generates yet.
As for storing a message that is potentially larger than a text field, in the past I've used a nibbler function to append 12k segments to an RT field which allows Domino to store the entire message . Not sure how that will work with your design though if you have to display that content in a Domino view. I'm also currently working on another project where I am the consumer of a web service. In this case we are using REST, not SOAP, and just the WinInet.dll to POST to a WebSphere based service running on an IBM Mainframe. If I can be of any service just let me know.
Best of luck!
Hi,
sounds odd. They claim to provide a Webservice and their users shall implement a producer*.
There is a seldom used "message exchange pattern" called Notification which would support a scenario like the one you described (if I have understand properly).
Searching on google for "Notification SOA" gives back some text which after a very quick scan seem to say that the Notification message exchange pattern isn't a good idea at all. What does happen if your subscribed server eh producer is down?
* afaik they call server producer and client consumer in SOA land.
Re: Axel's comment - do you have a System Architect contact on the project? If they have their wits about them, there should be a system diagram and / or data flow model to consult which should clarify what is happening.
On the surface there requirement seems odd, and I've not seen it externalized on the internet like this, but the general theory is sound. It's just an event/ listener or publish/subscribe model. This kind of model is extremely common in SAO architectures.
The court has data that it is publishing. Many clients want to subscribe to receive this data. Using common web service terminology flips everything on its head, but once you've got your head round it, it's fine.
This kind of model makes a lot more sense when you think about it occurring over an asynchronous transport, which you can do with SOAP. Again if you look at any web services stuff in a WebSphere Redbook, they go on and on about doing web Services over JMS/MQ. You could do it over Mail, but there are few (if any) SOAP stacks that hook up to mail for transport. Something that would be very cool to see Domino do.
Ok. Would like this to be shorter...
I believe the confusion point is the message exchange pattern thing.
Kerr. Hmm. sure. I am never been exposed to public/subscribe Messaging infrastructures. As far as I know the server eh publisher keeps track of the queue of individual messages yet to be sent out to the individual subscribers. Message transport reliability is the whole point. In a proper Messaging infrastructure the publisher only removes the message from the single clients queue if the subcriber-client aknowledged having received the message. So the infrastructure is robust with regard to message transport failures.
Kerr is right. They have build a system on this ideas with SOAP technology. The SOAP specification knows different message exchange patterns. There is not only
the Request/Response mechanism we are so used to (client itiates the communication by sending a message to server and expecting a response from server)
but also
- One-Way (the client initiates the communication by sending a message to the server)
- Notification (Server(!) intiates the communication by sending a message to client without expecting return)
- Solicit/Response (Server(!) intiates the communication by sending a amessage to the client and expecting a return). And thats the business case here.
In the specification those exchange patterns are supported by the WSDL with special combinations of xml-elements. But as I read in Monson Haefel book they are not all supported. He says that Notification and Solicit/Response aren't supported by J2EE Web Services because they are "[...] poorly specified by the WSDL 1.1 specification and tend to introduce more problems than they solve.[...]"
So they might want to build a system in the spirit of Solicit-Response Message Exchange Pattern without using the oficial spec for this case, because its poorly specified and for some reason difficult to implement by Web Service infrastructure providers.
hope this is not completly confusing
Axel
From a business logic standpoint:
US court is server.
Jakes client is client.
If solicit/response message exchange pattern were supported, Jakes client would be client also from a technical standpoint.
But as solicit/response message exchange pattern is not supported properly by Web Service infrastructres, Jakes client must technically be server and US court client.
For me makes sense.
Axel
That old Request_content size issue again...
{Link}
Sorry Peter, can't find any reference to the Request_Input in Lotus script, perhaps you are referring to the REQUEST_CONTENT field, anyway the above technote, shows that after 7.01 release the field is essentially broken into an array of chunks, that could be reassembled in a stream and/or appended to a richtext field through lotusscript or java before saving to the backend via the agent/servlet processing the ajax call.
The underlying issue is still the internal limit on notes text fields...
..but as you say nothing that can't be overcome...