web services question

[tom.baeyens]

kukeltje, do you have an idea how you are going to expose the command service as a web service ?

the service on itself, does not seem to be the problem. but it is the command and return value objects. i don't know how you are going to map these to XML.

have you already got an idea ?

[kukeltje]

The command objects also do not seem to be the problem since they are specifically typed (NewProcessInstanceCommand etc). The return value objects are more challenging but not big. The names of the methods, 'overloading' etc are more challenging if we wont those to be composite or not.

E.g. ending a task while passing variables, or separate them (set variables, end task)

This weekend I'm trying to create an xsd/wsdl for some commands to see what can be genrated and if the restult is acceptable.

I'll post the results when I have them, so everybody can check.

[tom.baeyens]

i mainly want to know how you envision the java/XML mapping to be done: will it be based on jaxb, custom parsing/xml-generation, ... ?

will only a few out-of-the-box commands be supported or can users easily add support for their commands and return values.

[kukeltje]

ahh ok, The initial trials were handcoded. The best/easiest/standardized (in no order of preference) way of mapping is what I'm looking into. It could be that they can map easisly on commands, but then they have to be aligned. There are 2 options I'm investigating:

<command name="startProcess">
 <processDefinition>
 <name>procName</name>
 <version>1.0</version>
 </processDefinition>
 <variables>
 <variable>
 <name>damageDate</name>
 <value>090906</value>
 </variable>
 <variable>
 <name>amount</name>
 <value>191916</value>
 </variable>
 </variables>
</command>

Personally I'm more in favour of:



procName
1.0



damageDate
090906


amount
191916

[kukeltje]

AAAHHHHHHHHHHH sorry, forgot to do a final preview


ahh ok, The initial trials were handcoded. The best/easiest/standardized (in no order of preference) way of mapping is what I'm looking into. It could be that they can map easisly on commands, but then they have to be aligned. There are 2 options I'm investigating:

<command name="startProcess">
 <processDefinition>
 <name>procName</name>
 <version>1.0</version>
 </processDefinition>
 <variables>
 <variable>
 <name>damageDate</name>
 <value>090906</value>
 </variable>
 <variable>
 <name>amount</name>
 <value>191916</value>
 </variable>
 </variables>
</command>

Personally I'm more in favour of:

<startProcess>
 <processDefinition>
 <name>procName</name>
 <version>1.0</version>
 </processDefinition>
 <variables>
 <variable>
 <name>damageDate</name>
 <value>090906</value>
 </variable>
 <variable>
 <name>amount</name>
 <value>191916</value>
 </variable>
 </variables>
</startProcess>

But this is not so extensible... If we make all elements optional, adding custom commands will be easier in XML, but they still have to be mapped. to either methods that did not exist or add some kind of config to fiond these base on reflection or whatever. Extending commands should benefit all and just be in the code. So I'm looking into the latter solution. I want to generate and XSD first with the commands in mind, but if some coding needs to be done, so be it.

[tom.baeyens]

why do you mention the xsd. if i look at your examples (which is very similar to what i want), i see a very limited schema that is fixed for all commands:

<command name="[xsd:string]" [other attibutes optional]>
 [any mixed content]
</command>

then at the server side, we would need a mapping command names and ParsableCommand classes.

do you think it would be suitable if we would use DOM for this parsing/generation of XML ?

then a ParsableCommand parser interface could look like this:

public interface ParsableCommand {
 Element execute(Element element);
}

then we need to write the infrastructure for 1 document style webservice with one method that unwraps these command from the SOAP envelopes, extract the command DOM element, lookup/instantiate the appropriate parsable command and invoke the execute method.

is that close to what you had in mind too ?

but i don't know yet which java WS technology we can use to implement this kind of infrastructure.

[kukeltje]

So you prefer 1, while I prefere 2.

Using 1 makes it impossible to generate any good client since anything is allowed. In the second version, you can have defined complex types per command. I prefere that one. Errorhandling is more simple since it comforms to an xsd or not. We do not have to program the checking of the '[any mixed content]' in relation to the name. So therefor I mention an XSD (and WSDL) . I tried this with the eclipse webservice explorer and could control the process from there with explicit commands and corresponding fields.

JSR-109 seems perfectly capable for this. No DOM parsing needed if you use example 2 and not one.

Maybe we should flip a coin or let Alex decide. He is the webservice guru ;-)

[kukeltje]

btw, I've been trying to use a php wsdl framework and with the second solution I got a client generated within minutes... cool huh?

[tom.baeyens]

"kukeltje" wrote:
So you prefer 1, while I prefere 2.

i don't really have a preference about how the schema looks like. in both cases it is readable. more important is which techniques we'll be using to do the java-to-XML conversion and the SOAP framework we'll use for exposing our webservice.

So you would start with JSR 109: Web Services for Java EE, Version 1.2
This relies on JAX-WS (next version of JAX-RPC) and JAXB 2.0.

I don't know these technologies. But my concern is: how easy or hard will it be to create new commands and expose them through that web service ?

I want to get a better understanding of the ins and outs going from development to deployment:
* we need a J2EE 1.4 container
* we have to put @WebService in the CommandService SLSB ?
* we have to generate the JAXB bindings from the command beans themselves ? is it hard to customize ? do you think that will be needed often or will the default name mappings be sufficient ?
* anything else we need to do ?

You don't have to convince me yet... cause i just don't get it yet. One way to get more insights is if you just go ahead and implement the basic structure. So that we can have a look out how it works.

Alex's opinion is always appreciated.

[kukeltje]

So you would start with JSR 109: Web Services for Java EE, Version 1.2
This relies on JAX-WS (next version of JAX-RPC) and JAXB 2.0.

Yes, can be generated by jboss-ws, maybe with as small 'wrapper' class

I don't know these technologies. But my concern is: how easy or hard will it be to create new commands and expose them through that web service ?

Depends on the signature of the commands, but in general not to hard. The initial configuration was tough, but adding new commands could be done in hours

I want to get a better understanding of the ins and outs going from development to deployment:
* we need a J2EE 1.4 container

No, can run with jboss-ws in tomcat

* we have to put @WebService in the CommandService SLSB ?

No, no SLSB is needed just the command objects, what you describe is JSR-181, WS for J2EE 1.5/EJB3

* we have to generate the JAXB bindings from the command beans themselves ?

This is what I want to try yes and then put this command object in the commandexecutor

is it hard to customize ?

Depends on what you want to customize. If you want new ws calls for which no commands exist it is more difficult. If we just use the JbpmContext and e.g. implement HQL in there it is not difficult.

do you think that will be needed often or will the default name mappings be sufficient ?

Depends on the amount of effort we want to put in there initially. I have a list from a customer that is limited, but usable for them

* anything else we need to do ?

Not much afaik

You don't have to convince me yet... cause i just don't get it yet. One way to get more insights is if you just go ahead and implement the basic structure. So that we can have a look out how it works.

I'll try to get an example up and running before the weekend is over since I'll be on Aruba the two weeks after that. I do not want to check it in yet though since I've made changes to the build scripts (there is a ws dir now) and some libs are required that are not in the repository yet (afaik). How can we communicate this?

Alex's opinion is always appreciated.

Agree

[tom.baeyens]

please provide a list of libraries that are required for web services and mark the ones that are not yet in the repository.

did you do any changes to the jbpm cvs repo outside of the ws subproject ? if not, that makes it much easier to just check in and evaluate afterwards.

did you put the ws subproject under jpdl/ws ? if not, please argue why.

[aguizar]

I hadn't had a chance to follow this topic. Hopefully my input will still be useful before Ronald goes to Aruba :)

In general you should defer as much Java-XML binding to the web services stack as you can. Custom parsing should be avoided as it is hard to optimize. Something like:

<command name="[xsd:string]" [other attibutes optional]>
 [any mixed content]
</command>

maps, per JAX-RPC rules, to

class Command {
 String name;
 SOAPElement _any;
}

The SOAP stack parses the [any mixed content] to produce the SOAPElement. Then the application processes the SOAPElement to produce Java objects. Result: two separate binding steps!

Plus, every command is a separate contract and should have its own document. Something like Ronald's proposal:

<startProcess>
 <processDefinition .../>
 <variables ...>
</startProcess>

is a lot better. What is unclear to me is how to introduce new commands. Is each of them a new operation in the WSDL port type?

[kukeltje]

Alex,

Thanks for the constructive comments

What is unclear to me is how to introduce new commands. Is each of them a new operation in the WSDL port type?

That was what I was thinking about. Do you have another Idea?

What I'm worried about is the kind of method overloading thing. If we put to much optional elements in one operation, we should still have multiple methods to the JbpmContext (although there we *can* have real method overloading, but how is this in the commands? I'm inclined to not use the commands but the JbpmContext directly. Any thoughts on this?

[aguizar]

Ronald,

Adding a new operation per command is fine; I wanted to confirm it was the approach you were following. The only alternative I can think of is a message-style endpoint. That option would take us back to deal with SOAP elements ourselves, tough.

We can do the "overloading" with the document bare approach. The command will be a single structure instead of individual parameters. By wrapping related optional parameters in separate elements, you can easily tell the 'overload' of the command being requested in the service implementation bean:

class StartProcessCommand {
 ProcessDefinitionInfo processDefinition;
 VariablesInfo variables;
}

class CommandServiceImplBean {

 public void startProcess(StartProcessCommand command) {
 ProcessInstance pi;

 if (command.variables == null)
 pi = jbpmContext.newProcessInstance(command.processDefinition.name);
 else
 pi = jbpmContext.newProcessInstance(command.processDefinition.name,
 command.variables.toMap());

 pi.signal();
 }
}

The above snippet is pseudocode, but you get the idea. I do not see a good reason to use the command facility as opposed to invoking operations in the jbpm context directly either.

[kukeltje]

I thought of message-style to, but so no real advantage.

Your pseudo code is exactely like what I did for my small personal demo. This gives me confidence I'm on the right track. For sure we can have a ws frontend to jBPM by the end of september (hey, I might even take my laptop with me now, and NOT just to store the pile of images of the beautiful girls^H^H^H^H nature)