[[BackLinksMenu]]
[[TOC]]
= Properties Library Tutorial =
The ProLib is a library written in Java which is intended to serve as somewhat an intermediate layer between client Sophie2 code and Java code. It has concepts and functionality which help solve a list of problems in an elegant (and hopefully efficient) manner. Its purpose is to ease the developer, not burden him, and in many cases leads to improved readability, more compact code which is also less error-prone if used correctly. Also, the problems which the ProLib solves are done (mostly) invisible to the developer so in the general case he shouldn't worry about how the ProLib works internally but just follow a set of rules and conventions for proper usage.

The ProLib is now in a relatively stable state, though there are still new ideas to implement and integrate inside it as well as some performance optimizations.

Basically, the structure looks like this:

[[Image(source:branches/private/gogov/PRO_LIB_CORE_TUTORIAL_R1/sophie2-platform/modules/org.sophie2.core/src/test/resources/Layers.png)]]

So, most Sophie2 client code is intended to use the ProLib in the cases when the ProLib solves problems and is helpful and use normal Java code in other cases.

== ProLib basics ==
 * ProObject vs Java Object
 * Propertry vs Java field
 * areaComputation example

[[Include(source:/trunk/sophie2-platform/modules/org.sophie2.core/src/test/java/org/sophie2/core/prolib/tutorial/AutoPropertyDemo.java)]]

== Problems Solved ==
The ProLib gives solution to the following problems:
 * Dependencies, initialization order and updating problems:
  * Diagram of dependencies and explanation of computation algorithm
 * Undo/Redo
 * Save/Load
 * Optimization (central point)
 * Safety (detect errors)

== ProObjects and Properties ==

=== ProObjects ===
[[Image(source:branches/private/gogov/PRO_LIB_CORE_TUTORIAL_R1/sophie2-platform/modules/org.sophie2.core/src/test/resources/ProObjects.png)]]

=== Properties ===
[[Image(source:branches/private/gogov/PRO_LIB_CORE_TUTORIAL_R1/sophie2-platform/modules/org.sophie2.core/src/test/resources/Property Hierarchy.png)]]
 * Interfaces
 * Fundamental
 * Single Properties
 * Multiple Properties

== A Little Bit Of Internals ==
  * 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..

  * Utils
   * !ReflectionUtil - Misc helper static methods.
   * !SwingUtil - Class which wraps a (legacy) !JavaBean for use in !ProBeans.
 * 
[[Image(source:/trunk/sophie2-platform/modules/org.sophie2.core/doc/Properties.png)]]

=== List properties hierarchy ===
[[Image(source:/trunk/sophie2-platform/modules/org.sophie2.core/doc/ProList.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);
	}
}}}

== Debugging ProLib ==
 * Inspector - A GUI tool that allows browsing the application state while it still works.

== Demo ==
 * Tutorial unit test demonstrating the usage of !AutoProperty


== 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