So, I want to distinguish two sorts of inputs/outputs. Both are important to document, but they should be documented in different ways.

One sense of inputs/outputs (which applies only to “full” services) is user inputs/browser outputs, business rules governing them, etc. Obviously, developers using the services need to know about these, but so do the users. I think user documentation of these inputs and outputs should suffice for most purposes.

The other sense of inputs/outputs that needs to be documented is really only of interest to developer consumers of the service, but it’s rather more limited. It’s just the inputs that the consuming application needs to pass to the service, the outputs it can expect in return, and the changes to the entity caches that the behavior translates into. The inputs and outputs that the application needs to pass/can expect can be documented just as you would write Javadoc (though obviously you can’t take direct advantage of the Javadoc engine to do so).

JAR files…I agree that versioning is the current weakest point of the methodology. But I don’t think it’s a deal-killer. For one thing, I think that, if you think of the deployed libraries as internal *releases* (in a very fast-cycle, Agile sense), and really use the centralized network instance of the JAR (which will always be the latest release, definitionally) as much as possible, then this sort of versioning won’t be a huge issue.

But I’m still not 100% sure that this is the best way to manage it. Here’s another possibility:

Each application, or service that relies on other services, has, in its build script (and I *strongly* recommend using build scripts, at least for deployment for a variety of independent reasons–though that’s a topic for a different post) which actually checks the latest version of the needed applications out of the source control system into a temporary area, compiles and JARs them, and copies them into the WEB-INF/lib area of the app, so that the built project will always have the latest version of all relevant libraries.

Since the deploy script will call the build script first, this version will also get into the deployed application. (This, obviously, is *not* treating the libraries as having fast production cycles, but rather requires a synch between libraries and apps at each phase: development/testing/production, which is less than perfect; that’s why I prefer the original methodology for this).

One impact of any of these systems is that, to take advantage of a new release of the service, the applications that use the service will need to be redeployed. I’m looking into the possibility that BC and Task Flow libraries don’t actually need to be deployed with the service but can just be added to the J2EE container’s shared classpath (I don’t yet know whether this is true); in that case a simultaneous deployment (via build script) to both the container shared classpath and the shared network location will assure that the latest release version is being used at both design-time and run-time (requiring only a JDev/container bounce to take effect, respectively).

Wow. That was a long reply. It was a very good pair of questions.

You can't keep a good idea down… Time and technical issues may have conspired to prevent Avrom…

Since you point it out as extremely important, how do you suggest that service developers need to maintain documentation to describe exactly what the inputs, outputs, and behavior of their services are. For example also for what you call “full” services (i.e., particular subtasks that involve a UI).

Preventing that these libraries, and their different versions, become a mess, seems quite hard in this Extreme Reusability methodology you propose.

regards
Jan Vervecken