[[BackLinksMenu]]
[[TOC]]
= Properties Library Tutorial =

== Properties Idea ==
Properties give solution to the sequence of problems:
 * Initialization order problems
 * Dependency/updating
 * Undo/Redo
 * Save/Load
 * Optimization (central point)
 * Safety (detect errors)
== Properties Heirarchy ==
  * !ProObject - Object with properties. All objects needing property support should implement this interface.
  * !ProBean - Each bean is associated one to one with a !ProObject.
  * Prop<T> - Basic interface to access all properties. While the Property class is the base class for the implementation, once implemented, the clients interested in the value of the properties should use this interface to access it.
   * Property - Basic class for all properties.
  * !BeanData - !BeanData holds the information (properties, etc of a bean, and also a behavior for the make methods).
  * !PropMetaInfo - Meta information for a property. Immutable.
  * !PropretyStatus - A state of a trackable object.
   * CREATED - initial state, you can only add/remove listeners
   * META_INITIALIZED - get will throw !NotInitialized exception, other methods will work
   * READY - get will return value
   * DESTROYED - again get will throw..
  * !ProExp - Manages property expressions.
  * Utils
   * !ReflectionUtil - Misc helper static methods.
   * !SwingUtil - Class which wraps a (legacy) !JavaBean for use in !ProBeans.
   * Inspector - A GUI tool that allows browsing the application state while it still works.
 * 
[[Image(source:/trunk/sophie2-platform/modules/org.sophie2.core/doc/Properties.png)]]
[[BR]]
[[BR]]
[[BR]]
=== List properties hierarchy ===
[[Image(source:/trunk/sophie2-platform/modules/org.sophie2.core/doc/ProList.png)]]
[[BR]]
[[BR]]
[[BR]]
=== Binding hierarchy ===
  * It is the existing bindings hierarchy but bindings are '''deprecated'''.
[[Image(source:/trunk/sophie2-platform/modules/org.sophie2.core/doc/Deprecated.png)]]
== Properties Kinds ==
 * Property
  * !ObjectProperty - A property which holds a reference to a single object.
   * !FinalProperty - One time write property. Once set, its value never changes.
   * !AutoProperty - Smart property. A property which automatically monitors the information it depends on. In order to work, it should rely only on other properties and immutable values.
   * !ResourceProperty - A property which holds a mutable resource. Useful for mutable non pro things like swing gui elements.  
   * !ValueProperty - A property that has a reference to an object and allows getting and setting it.
    * !ParentProperty - Property which will hold a link to parent for parent-child relations.
    * !UndoProperty - A property which holds the undo manager for given bean. If the bean does not have such property, the properties try to locate !UndoManager up (to parent). 
  * !ListProperty - Basic list property. Holds references to many objects.
   * !ChildrenProperty - Property which manages list of children for a child/parent relation.

== Code Examples with different Properties Kinds ==
=== How to make ===
 * !FinalProperty
{{{
        public Prop<FrameView> frameView() {
		return getBean().makeFinalProp("frameView", FrameView.class);
	}
}}}

 * !AutoProperty
{{{
	public Prop<JScrollPane> scrollPane() {
		class scrollPane extends AutoProperty<JScrollPane> {
			@Override
			protected JScrollPane compute() {
				JScrollPane res = new JScrollPane(list().get());

				res.setVerticalScrollBarPolicy(
						ScrollPaneConstants.VERTICAL_SCROLLBAR_ALWAYS);

				return res;
			}
		}
		return getBean().makeReadProp(scrollPane.class);
	}
}}}


 * !ResourceProperty
{{{
	public Prop<JMenu> swingMenu() {
		class swingMenu extends ResourceProperty<JMenu> {

			@Override
			protected JMenu create() {
				return new JMenu();
			}

			@Override
			protected void destroy(JMenu resource) {
				// TODO Auto-generated method stub
				
			}

			@Override
			protected void setup(JMenu res) {
				List<MenuMember> data = items().get();
				assert data.size() == 0 || Collections.frequency(data, data.get(0)) == 1 : data;
				
				res.removeAll();
				for(MenuMember m : data) {
					res.add(m.swingMenu().get());
				}
			}
		}
		return getBean().makeReadProp(swingMenu.class);
	}
}}}

 * !ParentProperty
{{{
        public RwProp<Page> parent() {
		return getBean().makeParentProp(Page.class, "frames");
	}
}}}

 * !UndoProperty
{{{
        public UndoProperty undoManager() {
		return getBean().makeUndoProperty();
	}
}}}

==== Methods To Use ====
These are methods of the !ProBean class.
 * Creates a read-write value prop by given property class.
{{{
        public <T> RwProp<T> makeRwProp(Class<? extends ObjectProperty<T>> cl) {
		return makeProp(cl);
	}
}}}

 * Creates a read-only prop by given property class.
{{{
	public <T> Prop<T> makeReadProp(Class<? extends Property<T>> cl) {
		// XXX access exposure
		return makeProp(cl);
	}
}}}

 * Makes (or returns if already made) a simple value property by the given information.
{{{
        public <T> RwProp<T> makeValueProp(String id, Class<T> valueClass) {
		return getData().makeValueProp(id, valueClass);
	}
}}}

or 

{{{
	public <T> RwProp<T> makeValueProp(String id, Class<T> valueClass,
			T initValue) {
		return getData().makeValueProp(id, valueClass, initValue);
	}
}}}

 * Creates a children property.
{{{
        public <T extends ProObject> ChildrenProperty<T> makeChildProp(String id,
			Class<T> childClass) {

		return getData().makeChildProp(id, childClass);
	}
}}}

 * Creates a parent property.
{{{
	public <T extends ProObject> ParentProperty<T> makeParentProp(
			Class<T> parentClass, String childPropId) {
		return getData().makeParentProp(parentClass, childPropId);
	}
}}}

 * Creates a list property.
{{{
	public <T> RwListProp<T> makeListProp(String id, Class<T> elementClass) {
		return getData().makeListProp(id, elementClass);
	}
}}}

or

{{{
	public <T> RwListProp<T> makeListProp(
			Class<? extends ListProperty<T>> propClass) {
		return makeProp(propClass);
	}
}}}

 * Makes (or returns if already created) a final property (whose value may be written only once).
{{{
	public <T> Prop<T> makeFinalProp(String id, Class<T> valueClass) {
		return getData().makeFinalProp(id, valueClass);
	}
}}}

 * Creates (or returns if already have) an undo manager of this bean.
{{{
	public UndoProperty makeUndoProperty() {
		return getData().makeUndoProperty();
	}
}}}

=== Bad Code Examples ===

 * Resource Property is a better choice.

{{{
        public Prop<JComponent> swingComponent() {
		class swingComponent extends AutoProperty<JComponent> {
			@Override
			protected JComponent compute() {
				JComponent res = new JPanel();
				res.setLayout(new BoxLayout(res, BoxLayout.Y_AXIS));
				res.setPreferredSize(new Dimension(100, 100));
				res.add(headComponent().get());
				res.add(scrollPane().get());
				res.setVisible(true);
				res.validate();
        
				return res;
			}
		}
		return getBean().makeReadProp(swingComponent.class);
	}
}}}

== Demo ==
 * Tutorial unit test demonstrating the usage of !AutoProperty
[[Include(source:/trunk/sophie2-platform/modules/org.sophie2.core/src/test/java/org/sophie2/core/prolib/tutorial/AutoPropertyDemo.java)]]

== How to apply properties to Sophie 2.0 ==
 * To get rid of the fields, except for immutable classes, and public static final things.
  * Note that final instance fields are not so safe, because they are initialized after the super constructors.
 * To convert mutable classes to !ProObjects
 * To gather more requirements to the properties library and apply them
 * To keep the properties library with high quality, because everything else will depend on it.
 * To be careful of cyclic dependencies (like a = b + 1, b = a + 1). No library can solve them.

= Comments =
 * The tutorial should be updated with the new things about properties - @Own annotation, deprecation of ChildrenProperty, etc. --boyan@2009-01-12