svn commit: r1491390 - in /isis/site/trunk/content/applib-guide/reference/recognized-annotations: SortedBy.md images/ images/sortedby-dependencies.png

[da...@apache.org]

Author: danhaywood
Date: Mon Jun 10 09:50:29 2013
New Revision: 1491390

URL: http://svn.apache.org/r1491390
Log:
isis-430: @SortedBy annotation

Added:
    isis/site/trunk/content/applib-guide/reference/recognized-annotations/SortedBy.md
    isis/site/trunk/content/applib-guide/reference/recognized-annotations/images/
    isis/site/trunk/content/applib-guide/reference/recognized-annotations/images/sortedby-dependencies.png   (with props)

Added: isis/site/trunk/content/applib-guide/reference/recognized-annotations/SortedBy.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/reference/recognized-annotations/SortedBy.md?rev=1491390&view=auto
==============================================================================
--- isis/site/trunk/content/applib-guide/reference/recognized-annotations/SortedBy.md (added)
+++ isis/site/trunk/content/applib-guide/reference/recognized-annotations/SortedBy.md Mon Jun 10 09:50:29 2013
@@ -0,0 +1,44 @@
+@SortedBy
+-------
+
+> **Support**
+> 
+> * Supported by: Wicket viewer; not yet supported by other viewers.
+
+The `@SortedBy` annotation is an instruction hint for (`SortedSet`) collections to use the specified comparator rather than the natural ordering of the entity
+(as would usually be the case).
+
+For example, this is taken from the [quickstart archetype](../../../getting-started/quickstart-archetype.html):
+
+
+    public class ToDoItem implements Comparable<ToDoItem> {
+
+        ...
+        public static class DependenciesComparator implements Comparator<ToDoItem> {
+            @Override
+            public int compare(ToDoItem p, ToDoItem q) {
+                return ORDERING_BY_DESCRIPTION
+                        .compound(Ordering.<ToDoItem>natural())
+                        .compare(p, q);
+            }
+        }
+
+        ...    
+        @SortedBy(DependenciesComparator.class)
+        public SortedSet<ToDoItem> getDependencies() { ... }
+
+
+        public int compareTo(final ToDoItem other) {
+            return ORDERING_BY_COMPLETE
+                    .compound(ORDERING_BY_DUE_BY)
+                    .compound(ORDERING_BY_DESCRIPTION)
+                    .compare(this, other);
+        }
+        ...
+    }
+
+When the `Dependencies collection is rendered, the elements are sorted by the `description` property first:
+
+![](images/sortedby-dependencies.png)
+
+Without this annotation, the order would have been inverted (because the natural ordering places items not completed before items that have been completed.
\ No newline at end of file

Added: isis/site/trunk/content/applib-guide/reference/recognized-annotations/images/sortedby-dependencies.png
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/reference/recognized-annotations/images/sortedby-dependencies.png?rev=1491390&view=auto
==============================================================================
Binary file - no diff available.

Propchange: isis/site/trunk/content/applib-guide/reference/recognized-annotations/images/sortedby-dependencies.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream