Code contains knowledge about the application and not only the commands to execute that application, this is a thing that is a bit unknown.
Meaningful names for classes/methods, etc… will expose the knowledge buried in the code better to a person working with that code. When you are changing the behavior of a method or a class it is a good policy to also change its name in order to expose the behavior of that class better.
The knowledge of an application should not be encapsulated only in UML diagrams or PowerPoint documents, it should be encapsulated into the code itself because easier to read code translates into a better application.

I have become interested lately into knowledge management. It is a pretty interesting field that applies pretty well to software development.

Later Edit: In the ideal case a person could learn a bit about the domain by going over the APIs, in such an environment you could say that the domain knowledge is pretty well encapsulated in the code. Of course, this would not mean that the domain knowledge should only exist in the code, only that it is a desirable to have the code reflect the domain.

I was listening to this presentation by some people at ThoughtWorks about designing an application when I was struck by this quote which goes roughly like this:
I keep thinking of clever designs to push the technology out of the picture so that changes in the business domain can be implemented more easily.

Very clever quote. The business domain keeps changing a lot more frequently these days, I think due to an increase of the number of stakeholders which increases the variety of requirements, so it is imperative to be able to make those domains changes easily. Being unable to make these domain changes because of technological reasons carries a pretty big cost.
This is why the technology should take a back seat to the domain. Ideally it would be abstracted so that it is decoupled from the domain.

Another quote that I liked was: you are given a domain when you start working on a project, you are not making this domain up and that your implementation should reflect very well that domain. The job of the domain modeler is to find out that domain and then represent it as faithfully as possible. The domain will change, but it not change in a radical fashion because this would imply that the underlying business changes radically and this doesn’t happen that often.
As I was saying before, the domain changes more frequently these days so it is better to have your application very well aligned with the domain so that changes in the domain can be translated into changes in the application very easily. If you cannot add a new feature because some framework doesn’t allow you to then you have a pretty big problem.

Another big theme in this panel was how to defer decisions till the last possible moment, which is a pretty neat things: it pays off to make decisions later when you probably have more information to base your decisions on.

All in all, a pretty interesting presentation.

I was reading this post from Bill Burke’s blog and I found myself shocked by the sheer number of annotations required for making a business object WS-BA compatible (if I understand well the post).
One thing that I don’t like about using annotations is that they tend to stay with the code. I think that these documentation provided by annotations should be outside of the code because in this case you are coupling your business component to an external concern: you are coupling your component to the WS specification.
What you get in Bill’s post is the first stage of annotation creep: you need to externalize your component in order to plug it into an operational environment and you do it thru an annotation. Next operational environment comes with a brand-new set of annotations. And so on…
I keep thinking that the best way to deal with all these annotations would be to sub-class the original interface and apply annotations to it. You will have quite a lot of problems: the classes which are mapped to the original interface will need to be sub-classed as well and their sub-classes mapped to the annotated interface. You will have problems when updating the original interface, you will find that you need to update all its annotated sub-interfaces. And a whole other set of problems.
You feel like you almost need to define inheritance in annotations: an interface would inherit the methods from an interface and the annotations from a different place and you would work with this new interface properly annotated for the operational environment. My opinion is that annotations, like any other type of static, hard-to-change documentation, have serious limitations when it comes to exposing a class to many, varied environments and when you are using it for documenting operational concerns. No wonder so many people prefer XML…

BTW, this post uses Bill Burke’s post only for displaying an example of annotation-creep.

Later edit: If you think about the way annotations are currently used (putting them all over your code base in order to insert a component into various frameworks) they can be thought of as some sort of cross-cutting concerns (they are cross-cutting to a certain extent). I wonder if using something like an aspect would not do a better job of expressing the various concerns that annotations are currently used for. Aspects are orthogonal to the code-base at the same time, a pretty neat thing.
Wouldn’t it make sense to WS-BA-enable your whole application by specifying a point-cut and then applying annotations against this point-cut? It would be a lot easier and it would de-couple your code-base from external concerns. I am not sure if it is doable (I could think of a solution, but it is not pretty).
I think that the way annotations are currently used is not 100% OK and that it poses some maintainability problems in the future. Putting information into annotations is partly a response to XML-creep (as Bill Burke pointed out in the comments) but it is a solution far from perfect. What we are dealing with here is the need to add some information to a component in order to plug it into a framework. Annotations, as well as XML, are not doing a good job because they address this problem (plugging the component into the framework) at the individual level, at the component level. What we really need is a mechanism that would let you plug a whole set of components into a framework easily (I suggested using point-cuts).

Later Edit 2.0: I think that adding querying capabilities at the code-base level (similar to AspectJ`s point-cut language) along with a mechanism to interpret these queries into Java would be the killer feature that Java lovers wait for. It would create a whole new way of developing: for example AOP would be implemented by joining point-cuts to an interception mechanism. A lot of the current mappings (in XML or in annotations) could be solved by defining a point-cut and then a mechanism to interpret this point cut. In the above case you would define a point-cut of your components that you want to WS-BA-enable and a mechanism for working with the components returned by this point-cut. Embedding a framework into an application would consist of creating a point-cut and then passing it to the framework in order to process it.
This would be application-level introspection and reflection and it would do away with both annotation-creep and XML-creep. I can`t dwell too much on it cause I gotta go to sleep.

Later Edit 3: In this post Bill Burke argues about using meta-annotation in order to de-couple your code-base from framework specific annotations. Adding a level of indirection between framework-specific annotations will free your application from framework-specific dependencies, this is for sure, but you will still tie your code to a representation (the representation specified by your annotations that serve as end-points for the original framework specific annotations). I am not sure that this is desired. I still think that your code-base should not be polluted by any external concerns.
It is interesting to see what will happen:
1) Will the world continue with annotation-creep and XML-creep for plugging their applications into various frameworks?
2) Will the world settle for a mid-way solution, like the meta-annotation solution suggested by Bill for the same problem?
3) Will the world try to solve this thru a different design?
4) Will the world decide that frame-work plugging is so costly that we might as well migrate to a different language/platform in order to reduce these costs?
It is all a question of supply and demand basic economics: plugging an application into a framework is currently a pretty costly operation. If the demand for this operation rises significantly (the number of times an application is plugged into a framework increases) it would make sense to make an investment (new methodology, new framework, etc…) in order to slash the costs. Either you make the investment or your language/platform becomes so costly so that it will prove cost-effective to move to a different language/platform.

You are probably familiar with various management consoles that various application servers provide you with in order to manage your application. The problems that these UI consoles have are the problems that any UI has once the number of features starts to grow: they simply run out of space (most of the time the space available for displaying your app server console is a web page which is fixed in size). If you ever looked at Weblogic 10`s management console you probably noticed the 3-level menus that are trying to lock a developer onto the feature they need to change. Well, as I was saying in a previous post, this approach doesn`t scale because you will be running out of space. I wonder when will Weblogic`s management console have 7-level menus given the speed at which features are getting added to app servers.

One other problem that the an UI management console puts forward is that it makes a developer (a person that usually is fluent in a few scripting languages) use a UI which is wasteful. It is wasteful because it wastes one of your most precious resources: the fact that your developer is a developer and that developers are familiar with scripts. UI solutions reduce your developer to the level of an ordinary user whose knowledge about an app server is reduced to the knowledge of various entities managed by your app server (servers, connection pools, datasources, applications, JMS queues, etc…) and the knowledge of clicking along. A developer would probably be more productive if it could take a look at its operational environment, determine various tasks which occur often and script up a solution to solving these tasks rather than clicking away. This is a lot better when you are perfoming composite tasks like adding a connection pool, exposing it thru a data source, adding this datasource to various servers and re-starting the servers to load the datasource. It makes a lot more sense to put up a script solution if you have to carry out these tasks across a cluster for the simple reason that you may forget to carry out a task for servers (or worse, for a series of servers).

Another problem with UI management consoles is that the error factor is higher: it is possible to click on the wrong button - `Do you really want me to shut down this server?` - and that it takes a long time to carry out a task. This it the problem with humans, they are slow and error-prone.

Now a bit about the languages used for creating management scripts. Given that most of the tasks that would be scripted are variations on the same theme (repetition occurs pretty often when you are managing servers) it would make sense to use a language in which you could define templates easily. An OO language (such as Ruby) would probably make a lot of sense. ant is good (and Weblogic lets you admin your app server thru ant tasks) but ant can only go so much.

One last advice that I would have would be to avoid duplication of scripts. I am saying this because Weblogic lets you create scripts for managing your server both in Python and in ant. You should avoid duplication and settle for one language.

Moving from an UI-based management console to managing your app servers thru scripts is a pretty dangerous task. If you are not careful and don`t plan this move well you may end up with a lot more problems. Think about managing your servers thru scripts as of programming your operational environment, the same problems that programming poses will arise in managing your operational environment. Bloat-ware, feature-creep. code duplication, etc… may rise to haunt the way you manage your app servers if you don’t write your scripts carefully. You would be well advised to try to do your best to avoid such problems, because they are very hard to solve once they appear.
What makes them `coding` your environment very hard to solve is that the stakes are a lot higher in this case than for your typical code blunders: your operational environment will depend on the way you `coded` it and the costs of refactoring these management scripts are huge: your entire cluster could go down if you are not too careful. A developer with a lot of experience would probably be needed to supervise this exercise.
P.S. It would probably not be a bad idea if in addition to providing a JMX interface to your application for managing your application, a JMX interface that can be displayed in an app server`s management console, you could also provide an ant task which would carry out the same operation on the application deployed on the app server remotely. I am not sure if this is actually possible (I think that one good solution would be the app server exposing the JMX interface thru an ant task) but it would be pretty nifty.

P.P.S I wrote this post because I had nothing better to do. Take it with a ton of salt.

You are probably familiar with the template design pattern. It lets you define a life-cycle and declare functionality unknown at design time in abstract methods, effectively delegating this functionality to the sub-classes. While initially described in C++ terms in the famous Go4 book it is widely used in Java applications (Spring uses it heavily for managing connections of all sorts: JDBC, JMS, etc…)

In Java it is a pretty limiting pattern: due to the single inheritance rule you cannot have the sub-class of a template (let’s call it “templated” class) extend multiple super-classes. Sometimes this is pretty limiting, I find it. One work-around to this problem is to change the template class so that it is not abstract anymore and declare all the abstract methods in an interface (the “life-cycle” interface) which the template class is using as a member variable. Then the interface would be implemented by a “templated” class which doesn’t need to sub-class the template class, which gives the “templated” class more freedom. The template class will be populated at run-time with the appropriate interface implementation thru an IoC mechanism. I find that the life-cycle defined in the template class can be extended as well by defining a sub-class of the “life-cycle” interface which could extend its contract. This way you can define more flexible life-cycles. (You can do the same thing with the traditional template design pattern as well but I find it to be harder).
I find that this arrangement pretty much does away with the template design pattern and makes your application more flexible by eliminating the need for sub-classing.

One interesting question would be why the above approach (the interface-flavored template) has not been used before and the template design patten has been used extensively? I have 2 answers to this:
1) The template design pattern pretty much casts in stone your life-cycle. Once defined the life-cycle can be changed only at great costs, and some times the stability given by this inflexibility is desired.
2) The drop in the cost of interface-to-implementation mapping with the introduction of IoC. Before IoC interface-to-implementation mappings were usually constructed with tons of factories (another rather inflexible design pattern) and with tons of overhead. With IoC the interface-to-implementation costs plummeted weakening the case for the template design pattern.

It would be interesting to see how the template design pattern will evolve. Ironically enough it is a design principle championed by the architects of the most popular IoC (Spring) so there is some backing for it. It gives some stability to the architecture by making its extension harder, this could be desired in some applications. The flexibility generated by the interface-flavored template comes with some management costs: you need to manage the relationships that will be spawned because of the use of this method.
Time will tell…

P.S.: One key difference between the “old-style” template and the interface-flavored template is the inheritance issue: in the old-style template you export the life-cycle thru inheriting from the template class (and you have only one chance at inheriting a class in Java) while in the interface-flavored one you export the life-cycle by defining it in an interface (which can be inherit from multiple sources). The “templated” class will not have a chance to inherit from another class in the old-style template, while it will be able to extend another one in the interface template. I think that because of this big difference the old-style template doesn’t scale well: its mechanism for exporting the life-cycle (sub-classing) cannot be re-used, I have not spent too much time thinking about it.
Another difference between the 2 approaches is that the ‘original’ template pattern puts together the lifecycle definition (the abstract methods) and the lifecycle execution (the code calling the abstract methods) in one place: the template class. The interface method splits this in 2 parts: the life-cycle definition is in the interface and the lifecycle execution is in a class using the lifecycle interface. Sometimes you may need the de-coupling given by the interface template pattern.

While posting to this blog I have been using the term “transparent” a lot, transparent usually meaning making changes to a system without touching its internal mechanism. More often than not I posted about using AOP for transparent programming.
What about when you do not have the chance of using AOP for influencing a piece of software? You would still like to implement the new functionality without changing its internal mechanisms because they are very expensive to change (regression testing being a top expense). Transparent development is all about that, is about looking at a piece of code, at how it is structured and at the relationships between various actors and then determining how to change it with minimal change. I find that treating various pieces of code (methods included) as black-boxes and building blocks helps. I use a cost-based algorithm for determining what pieces of code should be changed and what should be used as building blocks: if changing a piece of code requires significant regression testing then I assign it a high cost and use it as a building block. I use this method for dealing with code which is not documented and it works pretty well. It lets you go as deep as you can into the code without trying to reverse-engineer the hell out of it, it limits the reverse-engineering effort.
Sub-classing also help to apply behavior transparently: you change the methods that you want changed, and delegate the nitty-gritty stuff that you don’t want to go into to the original class.

The main value of a black-box is that it has a contract that has been tested and accepted by the user.

I was reading this interview with Arjen Poutsma on Spring Web Services when I came across this paragraph:
One of the newest additions is the Spring Web Services subproject, which according to the Web site “is focused on creating document-driven Web services [and] aims to facilitate contract-first SOAP service development, allowing for the creation of flexible web services using one of the many ways to manipulate XML payloads.”

This is pretty interesting. I am not sure if you have heard the case for contract-first WS, one argument is that the web-service is essentially an interface (since it exposes a contract to the outside world) and generating it from an EJB or a POJO (as it was the case a couple of years ago) would basically imply that you are deriving an interface (the WS) from a concrete implementation (the EJB or the POJO), which, as you probably agree, is brain-dead. Later edit: This way of relating to remoting has some OOP ideological shades: you are basically forcing OOP concepts (deriving an implementation from an interface and not vice-versa) onto something that may not need to conform to these OOP concepts (inter-system communication in this case).
However, I am not buying this 100% anymore. The reason that I am not buying this 100% is that WS is basically a remoting mechanism among a few others (REST being its main competitor)and the the emergence of different application assembly platforms (frameworks, applications, suites that let you compose an application out of components that are exposed). One popular application-assembly platform is AJAX (which I happen to believe has been hyped out of proportions). AJAX favors small envelopes and REST is probably a very good fit for it, so chances are that you will need to expose your app REST-style. But, who knows, you may need to expose it WS-style as well because one system only talks WS and it needs to talk to you so you would need to remote your app in WS as well. I would say that the fact that your application needs to talk to different systems in different ways means that remoting an application is a functionality best done transparently (I am stating the obvious). It also means that you cannot fore-see 100% the way your app will interact with other apps and the contract-first WS are probably limited to scenarios when you have complete control over the interaction between that application and the other systems (which doesn’t happen very often).

On a side note, remoting an application is essentially an exercise in communication, and the way you do remote an application reflects the various stake-holders and their degree of influence quite a lot. The use of WS is pretty much a picture of the way your organization manages its communication channels: contract-first WS would probably fit a top-down approach in which the communication between various IT assets is spec-ed out before-hand, while WS used for remoting an existing application would imply an approach in which the communication is delegated to the team supporting that application and that is responsible for how it communicates with the outside world.
Not that the 2 are mutually exclusive: you can have a contract-first WS (designed top-down by an SOA architect) piggy-back on an currently running WS which has been remoting an application for ages. Another reason why these approaches are not mutually exclusive is that they have different scopes: top-down interaction is coarse-grained (you can control only high-level issues from the ivory tower) while delegating some degree of control to the IT team supporting the application is fine-grained (they can expose finer access to the application). Depending on what you need from that application you will interact with it differently and thru different channels.
SOA is a bit about control of the IT assets and it is partly a backlash against delegating control to the IT teams. A right balance should be found between what should be managed centrally and what should be delegated and to whom.

P.S. I didn’t sleep well last night and it probably shows. Please leave a message if something is not clear (as it is probably the case).

I was reading this post on manageability.org when I came across this quote:
So banking om my own experience, the primary reason I never spent the effort to upgrade was that a lot of my data was not independent of the modules used for viewing them. The three main culprits were the Wiki system, the polls and the comments.
…
The lesson learned here is clear, never adopt a system where access to your data is tightly coupled to the code that renders it. The failure of Object Oriented Databases and Proprietary Code Repositories give ample historical lessons as why such an approach leads to failure over time. The flexibility afforded by a generically accessible data will always outweigh the benefits of structured data store access.

I never thought about this, but you can get locked into a particular piece of functionality. Functionality is usually tied to a particular business process, so you are basically locking yourself into a business process. Business process are transient and in today’s world in which change is the word of the day that particular business process will probably change in time as well. The coupling between your application and that particular business process will determine how easily it can be re-factored in order to align itself with the transformed (or new) business process. Process de-composition (emerging buzzword ;-), watch it carefully) will probably play a big role in taking care of all this. One idea is to break the process (or functionality) into blocks at various levels (from high-level to low-level) and then re-assemble these blocks so that they end up delivering the required functionality. In order to do this efficiently you need domain knowledge.

I was reading this post by Rod Johnson on the Interface 21 blog about Oracle Application Server and Spring when I came across this quote:
Because Spring provides a rich, portable transaction abstraction, it does the work under the covers of driving JTA and other APIs, so your code doesn’t need to know anything about the underlying infrastructure, and thus can take advantage of any proprietary APIs that give more control or greater efficiency. Spring supports both declarative and programmatic transactions, so you can layer transaction management onto POJOs that don’t know anything about it; or, if transaction management is part of your business logic, you can use a more elegant API that offers more features than JTA (*), isn’t tied to JNDI, and is much less verbose to work with.

Wow. Does this mean that Spring’s transaction semantics are starting to compete with JEE’s transaction semantics for mind-share, and ultimately, market share? In what DSL (**) should you model your transactions: the old way by declaring them in ejb-jar.xml or Spring’s way by declaring them in spring-conf.xml? Is there a danger that one of these languages will become obsolete? Is there a danger that the current transaction semantics in Spring could be forked in order to better utilize a specific app-server’s capabilities? Is there a danger that these new transaction semantics be irreconcilable with the ones in the next Spring version?

In an earlier post I likened the transparent container’s capabilities to LISP’s, particularly when it comes to defining new languages (**). Well, the transparent container may inherit one bad thing from LISP: language mush-rooming. LISP diverged into so many dialects that it became eventually impossible to use as a common platform. More and more DSLs could be created for various use cases, which will range from the very specific to the very generic. I think this is probably where the effort will lie in the future, in managing all these DSLs, in separating specificity from generic behavior in an efficient manner. The future announces itself to be pretty messy…

* It is an interesting exercise to muse on Spring’s lead in TX APIs. If the features they advertise are needed - and I think they are needed and, even more, they are tested by the market - you would expect the JTA people to include them in their spec, after all the spec would be missing good functionality which should be included. If the JEE body will not include these features it will pretty much admit to being irrelevant in this particular area and would be handing the baton to the Spring people. Or maybe the JEE body doesn’t see these features as being generic enough or not having broad appeal. Who knows…

** Spring 2.0 was released with this nifty feature: XML namespaces. This opens the door to defining your own specialized languages (let’s call it a Domain Specific Language, DSL) tailored to your needs and plugging them into Spring’s runtime.