Public Service Use: Auditing

I've put out a couple feelers to get an explanation for the full intention of the PublicService annotation. In the mean time, I've been doing a little digging of my own. There are two places that the intentions for this annotation may show up: Explicitly in code and implicitly in policy.

Explicitly the annotation is being used to assist services such as the Audit Service.



The audit component implementation relies on public service identifier interface to find public service methods. The implementation for the Public Service Identifier checks for the annotation to make its identifications.

I'll update this post with more explicit uses as they show up.

Will there be any implied policy in the Alfresco SDLC (software development lifecycle?) I don't know -- we'll see what Alfresco has to say about that; this is a good question for Paul Holmes-Higgin or David Caruana.

Personally I find the notion of a public interface much more interesting if it means I can count on it in some fashion because being marked as public sets parameters on the interface in the software development lifecycle. I am much more interested what this notion of public service could mean in terms of the SDLC.

As a customer dependent on a non standards based (although open) API, I need to know what I can count on, what to expect; I want predictability and stability.

Public Services

If you are looking for an architectural representation of Alfresco, the best wiki link I know of is here. This documentation does a good job of putting Alfresco in context with the application server, client applications and breaking down the high level components.

Two of the most important pieces of documentation we need to maintain is A: A diagram and a strong description of what the current architecture and B: A well described road map of where we are going and how we plan to get there.

I try to do my best to keep up with how the architecture is evolving. The way I do it is by downloading the HEAD of the SVN source base, looking at the changes as they come down and comparing them to my current understanding. If there is an unknown or a mismatch, I head for documentation.

Recently we have seen a new addition in the source base (many actually) but there are few that caught my eye and one that I want to investigate immediately: an attribute placed on service classes called @publicservice. What a public service is isn't really clear to me yet. I've thrown together a diagram that kind of illustrates how I break out the architectural structure of Alfresco in my mind and how I am imagining public services -- what they really are remains to be seen. I suspect the diagram has some errors in it. Also with respect to the public services I see some services that I would expect to be public but that are not marked public. For example, the Tenant Service -- a new service that allows the repository to host multiple clients simultaneously and independently. This could be A: because I am wrong in what I suspect a public service is or B: because the concept isn't yet being applied by the entire team yet. C: Other :)



From an architectural perspective the notion of a "public service" could be very important to me. I've looked at many open source frameworks and often wondered why there was no distinction between public and internal code. How can you exist without this distinction? How can you possibly plan to refactor your code without putting customers at great risk? From my perspective a public layer gives the community a contract that says "It's safe to develop against this -- the life-cycle, the maturity, deprecation and ultimately removal of this interface is well known and you can plan against it." This creates a safety net for the community and a means or a protected space for refactoring for the engineers and architects of the project. If you the consumer have violated this public contract and tapped something below it -- it's at your own peril.

The documentation for "public service" doesn't yet exist from what I can tell and the java doc is somewhat uninformative in that it says "Specifically indicate that an interface defines a public service." -- a bit like defining a word by using the word. What does it mean to be a public service? I am not sure yet -- but I was thrilled to find it there and it has been fun to speculate on what the Alfresco team is intending for it. I plan to get to the bottom of the following questions:

• What is the definition of a public service -- can we get it in the java doc?
• Can it be counted on -- Is there some sort of contract with the community?
• If so is there a some sort of documented life-cycle?

I'll be back with answers once I get them! If you have the answers post them in the wiki and link it here!

Exciting stuff.

Freedom of the Press and Enterprise Content Management are IMPORTANT

Freedom of the Press matters dearly to humanity
Affordable Enterprise grade content management matters dearly to Freedom of the Press.

I think Alfresco, having gone completely to GPL last year has the opportunity to play a huge role in making the world a better place to live in by enabling the Freedom and ability to publish.

Related:

Sasa Vucinic invests in free press

and

Peter Gabriel fights injustice with video