Documentation
Disclaimer: Palantir Technologies is not affiliated with, endorsed or sponsored by Palantir.net, Inc. Palantir.net's website is http://palantir.net
There are several interpretations of Model-View-Controller so we'll provide ours up front:
A Model is a class that implements BindableModel and provides getters and setters for JavaBeans-style named properties. A Model does not directly have knowledge of any Views or Controllers. It indirectly may refer to these through a list of listeners. Generally the code in the Model is not very complicated and only serves to keep the model data in a valid state.
A View is any class that holds a reference to a Model and depicts it in some way, shape, or form. Within the scope of this framework there is no need for a View to be tied to Swing or any other UI framework. A View has direct knowledge (i.e., a reference) to some number of Models and Controllers.
A Controller is a class that incorporates "business logic" or any large block of code that processes the data in a Model. The logic in the Controller can be arbitrarily complex. Typically the controller will take some number of Models as input, process some logic, and set values on the various models. Controllers only have direct knowledge (i.e., a reference) to Models or Controllers.
- Tutorial & Examples - a tour through a set of runnable examples that explain using the framework.
- More Examples - a list of examples included in the Cinch source tree.
- [Annotations Reference](Annotations Reference) - quick reference and links into the Javadoc and examples for the Cinch framework.
Cinch uses the type of the object passed into the Bindings.bind() call to determine how bindings should be created. This can cause some confusion if the run time type is different than you are expecting. For example, if you call bindings.bind(this) in some constructor, the this object may not actually be exactly of the type you are expecting. This can occur if you call a super constructor from a subclass. One potential problem here is if the subclass has a field name that shadows a superclass field name.
Another potential problem is if you bind the same object more than once. This can occur if you call a super constructor that calls bind() and then you call it again in your subclass. This will setup multiple bindings and depending on what they do could lead to problems. If you are writing an object that is likely to be subclassed you usually want to call bind in the highest superclass or bind outside the constructor after object creation.
Generally performance is not an issue. We have setup extreme examples of thousands of bound components and found that the bind call can cumulatively take up enough Swing thread time to be noticeable. Most of this time was spent in reflectively examining and indexing the bound class. This was never an issue for us but this time could effectively be eliminated by implementing some form of caching for each bound type.
Here's a few downsides to using Cinch (in Eclipse-centric speak):
- Call Hierarchy on @CallOnUpdate functions can be misleading
- Spurious unused function/field warnings, depending on visibility (can be 'fixed' with @SuppressWarning("unused"))
- Renaming or moving fields will not update the text strings in Cinch annotations
Hopefully you'll agree that the benefits of Cinch make up for these!
There is no specific threading management in Cinch. We generally follow a very simple rule that should be natural to all Swing programmers: only modify Models on the Swing thread. If you do this then everything should work out since the bindings fire immediately and any bound Swing components will be updated on the correct thread. In Palantir UI code, we make extensive use of SwingWorker to do work on final copies of model variables and then subsequent modify models in their done() methods. In this way the burden of threading is no different than what a typical Swing programmer has to deal with.
We'd love to see more @Bound components for both existing and 3rd party components.
At Palantir we use a version of the Cinch library that has weak binding listeners. This has had mixed results, it can lead to a reduction of some memory leaks, can cause other negative side effects, and can result in unexpected behavior if you don't fully understand this implementation. In this public implementation we only have strongly bound listeners.