Changes between Version 37 and Version 38 of PRO_LIB_CORE_TUTORIAL
- Timestamp:
- 07/14/09 14:06:30 (16 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
PRO_LIB_CORE_TUTORIAL
v37 v38 135 135 This is the base abstract implementation of the Prop<T> interface. 136 136 * It allows you to set an initial value to the Property by the init() method. [[BR]] 137 You should extend this class if you want to provide new Property kinds in the ProLib, like MapProperty for instance ( good luck and God bless you if you do it (:).137 You should extend this class if you want to provide new Property kinds in the ProLib, like MapProperty for instance (however this is a very difficult task and one is not recommended to do so, unless they know what they are doing). 138 138 * '''ObjectProperty<T>''':[[BR]] 139 139 This class extends Property<T> and provides the base usable implementation of Prop<T> used for dealing with single object values. … … 143 143 This is the base abstract implementation of the ListProp<T> interface. 144 144 * It provides basic get(), get(int index) and size() implementation. 145 You should extend this class if you want to provide new ListProperty kinds in the ProLib, like SkipListProperty (which internally uses skiplists) for instance (again , good luck and God bless (:).145 You should extend this class if you want to provide new ListProperty kinds in the ProLib, like SkipListProperty (which internally uses skiplists) for instance (again remember that this is not so trivial and one is not recommended to do so, unless they know what they are doing). 146 146 147 147 ==== Single Properties (BLUE) ==== … … 190 190 In order to create an AutoProperty, by convention you declare a method structure like the structure of the area() method which declares a local class which extends the AutoProperty class. The type argument of the local class should be identical to the type argument of the Prop which the area() method returns - after all an AutoProperty is a Property which computes a given value following some logic and that value has a type which in our case is Integer.[[BR]] 191 191 So you override the compute() method to provide the AutoProperty's value computation logic inside. You can provide an arbitrary complex logic inside. In this example whenever the width() and height() Properties change their value, the AutoProperty is smart enough to call the compute() method again and update its value.[[BR]] 192 '''Something very important:''' compute() will be recomputed only in the cases when some of the '''Properties''' used inside it change their value!! If compute() depends on some normal Java field, there's no way for the ProLib to know when this field has changed its value and then notify the AutoProperty to change its value!! '''There's no magic here!!''' Expecting the ProLib to detect that means hooking to JVM's system events and maybe bytecode instrumentation which obviously we don't want to use (:192 '''Something very important:''' compute() will be recomputed only in the cases when some of the '''Properties''' used inside it change their value!! If compute() depends on some normal Java field, there's no way for the ProLib to know when this field has changed its value and then notify the AutoProperty to change its value!! '''There's no magic here!!''' Expecting the ProLib to detect that means hooking to JVM's system events and maybe bytecode instrumentation which obviously we don't want to use! 193 193 * Actually, AutoProperties have a '''doSet()''' method, which can be overriden to provide setting manually a value of a given AutoProperty. This can be used in ''very rare cases'' when you have an AutoProperty X which depends on other Properties but also there's an AutoProperty Y which depends on X. So let's say that we need Y to have a valid value but at this stage of execution of our program we don't have all the Properties which X depends on initialized. That's when we can manually set the value of X, so Y gets property computed, and later, when all the Properties X depends on initialize, then X gets recomputed and Y respectively.[[BR]] 194 This should be used very rarely, so if you think you need this, consult first with someone else (:194 This should be used very rarely, so if you think you need this, consult first with someone else. 195 195 * There's a special case of AutoProperties which are '''const''' AutoProperties. Such AutoProperties depend on some other Properties, but their value should be computed only once. 196 196 For instance you can have this case: … … 225 225 * Also by convention, you annotate such AutoProperties with '''@Const'''. 226 226 227 * Although I think the above example is much more sophisticated, I also add this one by His Holy Meddleness requestalong with his comments:227 * Although I think the above example is much more sophisticated, I also add this one as proposed by one of the integrators along with his comments: 228 228 {{{ 229 229 The @Const AutoProperties rarely depend on anything, they are "bottom" properties that can calculate themselves by themselves only once. … … 244 244 }}} 245 245 246 '''Imprortant note''': I'll outline again the difference between @Const AutoProperties and FinalProperties: AutoProperties know how to compute themselves whereas Final and ValueProperties do not (they get their values from some user action or an external source in general).246 '''Imprortant note''': I'll outline again the difference between @Const AutoProperties and FinalProperties: AutoProperties know how to compute themselves whereas Final and ValueProperties do not (they get their values from some user action or an external source in general). 247 247 248 248 * '''ResourceProperty<T>''':[[BR]] … … 295 295 ... 296 296 }}} 297 * Further more, the setup() method can be "split" in pieces by the '''@Setup''' annotation. In the ResourceProperty descendant class you provide, swingComponent in our case, you can provide a multitude of methods which are annotated with @Setup and together they form the logic for updating the ResourceProperty. This is useful for mperformance reasons, because let's say you've got a very heavy setup() method which consists of logically independent parts P1 and P2, and P1 depends on some Property X while P2 doesn't depend on X so when X changes, P2 doesn't need to be executed again. Thus, providing two new setup methods which correspond to P1 and P2 leads to performance optimization (and capsulation of independent code in different methods) because the ProLib is smart enough to invoke only the needed setup methods. You should note though that the order of invoking the @Setup methods is undefined and you shouldn't depend on this because it can change.297 * Further more, the setup() method can be "split" in pieces by the '''@Setup''' annotation. In the ResourceProperty descendant class you provide, swingComponent in our case, you can provide a multitude of methods which are annotated with @Setup and together they form the logic for updating the ResourceProperty. This is useful for performance reasons, because let's say you've got a very heavy setup() method which consists of logically independent parts P1 and P2, and P1 depends on some Property X while P2 doesn't depend on X so when X changes, P2 doesn't need to be executed again. Thus, providing two new setup methods which correspond to P1 and P2 leads to performance optimization (and capsulation of independent code in different methods) because the ProLib is smart enough to invoke only the needed setup methods. You should note though that the order of invoking the @Setup methods is undefined and you shouldn't depend on this because it can change. 298 298 For example the above setup() method can be split like this: 299 299 {{{ … … 371 371 372 372 == Pros and ProLists == 373 '''Note''': For a more basic usage of the ProLib, you don't need to read this. If you do want to understand and use ListProperties effectively, then read (:373 '''Note''': For a more basic usage of the ProLib, you don't need to read this. If you do want to understand and use ListProperties effectively, then read... 374 374 375 375 [[Image(source:branches/private/gogov/PRO_LIB_CORE_TUTORIAL_R1/sophie2-platform/modules/org.sophie2.core/src/test/resources/Pros And ProLists.png)]] … … 379 379 * '''Pro''':[[BR]] 380 380 This is '''THE''' most fundamental interface in the ProLib though if you don't refactor the ProLib, you'll most probably never need to know it exists. [[BR]] 381 Basically a Pro is something which implements an Observer-like behavior so ProListeners can be attached and detached to/from it. So again, there's no magic in the ProLib, just some smart concepts, and actually detecting dependencies, automatically solving initialization order problems and getting automatic updates is implemented with the help of this Observer-like behavior laid down at the very foundations of the ProLib (:381 Basically a Pro is something which implements an Observer-like behavior so ProListeners can be attached and detached to/from it. So again, there's no magic in the ProLib, just some smart concepts, and actually detecting dependencies, automatically solving initialization order problems and getting automatic updates is implemented with the help of this Observer-like behavior laid down at the very foundations of the ProLib. 382 382 383 383 * '''Prop<T>''':[[BR]] … … 385 385 386 386 * '''List<T>''':[[BR]] 387 This is simply the standard Java interface List<T> (:387 This is simply the standard Java interface List<T>. 388 388 389 389 * '''ProList<T>''':[[BR]] 390 ProList<T> extends Pro '''and''' List<T> so it's basically a List which can be tracked for changes. Now you should understand why ListProp<T> extends Prop<ProList<T>> (:390 ProList<T> extends Pro '''and''' List<T> so it's basically a List which can be tracked for changes. Now you should understand why ListProp<T> extends Prop<ProList<T>>. 391 391 392 392 === Implementations(YELLOW) === … … 457 457 When this method is applied to any BaseProList<T>, it creates a '''TransformingProList<T>'''. This ProList<T> is basically a transformed view of another ProList<S>. The ProListTransformer<S, T> is a visitor object which, given a S element, decides how to transform it to a T object. You can create such transformers by extending ProListTransformer<S, T> and overriding its translate() method to provide your custom logic. 458 458 459 Now, here's an example which uses these ProLists as well as other of the ProLib stuff. It's from the EmbeddedBooksPalette. If you understand it, then you're cool (:459 Now, here's an example which uses these ProLists as well as other of the ProLib things. It's from the EmbeddedBooksPalette. If you understand it, then you will not have problems using it. 460 460 461 461 {{{ … … 500 500 501 501 == @Own & ParentProperties == 502 So, you've noticed I missed describing the pink ParentProperty in the Properties section (:Good for you, it shows that you read carefully.502 So, you've noticed I missed describing the pink ParentProperty in the Properties section. Good for you, it shows that you read carefully. 503 503 504 504 [[Image(source:branches/private/gogov/PRO_LIB_CORE_TUTORIAL_R1/sophie2-platform/modules/org.sophie2.core/src/test/resources/Parent Property.png)]] … … 527 527 * Sets the parent() Property of the Person hold by the jesus() Property, to the concrete Meddle instance. 528 528 * And also makes sure that other Meddles cannot "own" the same jesus(). [[BR]] 529 These two things actually mean that that ''each Meddle has its oooown... peeeersonal... jeeesus'' (:[[BR]]529 These two things actually mean that that ''each Meddle has its oooown... peeeersonal... jeeesus''. [[BR]] 530 530 Another thing to mention it is not mandatory to manually declare ParentProperties in @Owned ProObjects if you don't want to use the parent link but guarantee that the ProObjects is @Owned only by one parent. Currently the ProLib doesn't work like that though it will be fixed very soon because this should be true.[[BR]] 531 531 Also note that though ProLib automatically sets the ParentProperties with correct values, it happens at a later stage, after the creation of the ProObject instance, so if you use the ParentProperty inside the ProObject's constructor, for instance, PArentProperty will still be null. And this is normal! You should have this in mind and write code which takes into consideration both cases and acts adequately. … … 543 543 }}} 544 544 When you clone this Sheep, the question what to do with all the Sheep's Properties arise. In the case of @Shared, when the Sheep dolly1 is cloned, the new Sheep dolly2's account() will hold the same BankAccount which dolly1 has.[[BR]] 545 In this context we should mention that the ProLib also makes sure that if account was @Own instead of @Shared, then dolly2 won't have the same BankAccount (:545 In this context we should mention that the ProLib also makes sure that if account was @Own instead of @Shared, then dolly2 won't have the same BankAccount. 546 546 547 547 == @Immutable == … … 550 550 '''Note''': The ProLib doesn't ''ensure'' that object annotated as @Immutable change because this is equal (again) to doing bytecode instrumentation. It is just a convention which has to be followed. 551 551 552 == ProObjects, @Immutables and junk==552 == ProObjects, @Immutables etc. == 553 553 In OOP there are two kinds of objects - mutable and immutable. In the ProLib mutable objects are intended to be only ProObjects and immutable objects should either be annotated with @Immutable or expand the list of ''known'' immutables in the ProLib which currently is limited to standard JDK immutables like Integer, Double etc. Why is this important: 554 554 … … 568 568 * X is mutable but is not a ProObject. In this case obviously nothing can be automatically done by the ProLib to detect when X changes. 569 569 570 This means that you should follow the rules above in order to produce non-flawed ProLib code. In general you can use ProObject, Immutables and the rest is junk (:570 This means that you should follow the rules above in order to produce non-flawed ProLib code. In general you can use ProObject, Immutables and the rest is "junk". 571 571 572 572 == ProLists, findOne(), findAll(), ProUtil.getKey() and ListEntry == … … 604 604 ProLists are smart though so they act not only as lists but as maps. In the ProLib there is the concept of ''keys'' when using ProList, depending on what kind of items are inside: 605 605 * Immutables -- the ''key'' of an Immutable is the Immutable itself, 606 * ListEntries -- there is a ListEntry class which is basically a pair of a key and a value. The ''key'' of a ListEntry is its key (:606 * ListEntries -- there is a ListEntry class which is basically a pair of a key and a value. The ''key'' of a ListEntry is its key of course. 607 607 * others -- ''key'' is always null. 608 608 … … 676 676 677 677 == Good Practices == 678 * Use ProObject and Immutables when using the ProLib. The rest is junk. Although if you know what you're doing, you can find useful stuff in the junk (:678 * Use ProObject and Immutables when using the ProLib. The rest is "junk". Although if you know what you're doing, you can find useful things in the "junk". 679 679 * Convert mutable classes to ProObjects. 680 680 * Keep the ProLib and with high quality, because everything else will depend on it.
