Tools are a wonderful thing. We need tools for layout upgrades, for installing channels, for exporting channels, for changing user passwords, for...
So, in order to reduce the learning curve for new users of these tools, provide CLI tools for production independent of the source code, and support executing meaty code in other environments we should do the following for all our tools:
Write POJOs
Write our meaty code to be called from anywhere (CLI, AntTask, GUI, servlet).
- Throw and chain exceptions when something goes wrong (don't return null as an error condition in an API, don't "log and ignore") This makes sane, rich UIs with user feedback feasible.
Write front-ends to call the POJOs
Having factored your new tool as re-usable pojos, appropriate front-ends to the tool can be developed. Of course you don't have to implement all of these to initially share your tool – share early and often. But the best practice is to produce code factorization such that all of these implementations are possible, and then to implement those that make sense.
Ant tasks call the pojos
Write AntTasks to call from Ant that give good ant style feedback for missing/incorrect parameters.
main() methods call the pojos
Write main()s to call from CLI that give good CLI style feedback for missing/incorrect parameters.
Scripts to call the CLI implementations
Consider generating wrapper scripts when building uPortal to call CLI style tools. (probably would need to generate both *.bat and *.sh scripts)
uPortal channels / portlets call the pojos
Using uPortal to administer uPortal can be a beautiful thing, with its rich layout aggregation, groups and permissins APIs. Tools available from the command line should also be available via the live uPortal web UI.
Web services
Consider implementing your tool in terms of a live uPortal service offered by a running uPortal instance. These flavors of tools would front-end a service (which becomes a point of integration for other systems).
Suppose you write an Eclipse plugin
Rather ambitious. Maybe no one will ever do it. But the point is this: if you write an Eclipse plugin implementation of a tool for uPortal, it too should call the POJOs, the same POJOs that can be invoked via CLI tools or via the uPortal GUI. (Bonus points to the first person to actually write a uPortal tool as an Eclipse plugin.)