Jason Stonebraker avatar Jason Stonebraker committed 5e83db0

Edited online

Comments (0)

Files changed (1)

-# Welcome
+# What is the JSON Exclusion Marshaller
 
-Welcome to your wiki! This is the default page we've installed for your convenience. Go ahead and edit it.
+A Grails plugin that adds a convenience method to the Grails JSON converter for excluding class properties from the JSON converter's output.
 
-## Wiki features
+## Usage
 
-This wiki uses the [Markdown](http://daringfireball.net/projects/markdown/) syntax.
+```
+#!groovy
+// Given a TestStudent Domain Class
+def student = new TestStudent([
+    firstName: "Tobias",
+    lastName: "Funke",
+    gradePointAverage: 3.6,
+    studentID: "FS-210-7312",
+    socialSecurityNumber: "555-55-5555"
+])
+
+// When
+JSON.excludeForTeachers(TestStudent, ['socialSecurityNumber', 'id', 'class'])
+
+// Now let's actually use the "excluder" we just created.
+def json, resultTeachersWillSee
 
-The wiki itself is actually a git repository, which means you can clone it, edit it locally/offline, add images or any other file type, and push it back to us. It will be live immediately.
+JSON.use('excludeForTeachers') {
+    json = new JSON(student)
+}
+resultTeachersWillSee = json.toString()
 
-Go ahead and try:
+println resultTeachersWillSee
 
 ```
-$ git clone https://bitbucket.org/stonebraker/jsonexclusionmarshaller.git/wiki
+
+Outputs:
+```
+#!json
+{"firstName":"Tobias","gradePointAverage":3.6,"lastName":"Funke","studentID":"FS-210-7312"}
 ```
 
-Wiki pages are normal files, with the .md extension. You can edit them locally, as well as creating new ones.
+### Walkthrough
 
-## Syntax highlighting
+First we instantiate a simple object called TestStudent. Nothing magical here...
+```
+#!groovy
+student = new TestStudent([
+    firstName: "Tobias",
+    lastName: "Funke",
+    gradePointAverage: 3.6,
+    studentID: "FS-210-7312",
+    socialSecurityNumber: "555-55-5555"
+])
+```
 
+Next we make use of the excludeFor*() method. You can write anything that makes sense to your domain between "excludeFor" and "()". The whole method name is what you'll use next to marshall the object into the form you want.
 
-You can also highlight snippets of text (we use the excellent [Pygments][] library).
+We specify which properties a teacher is allowed to see by creating an "excluder" (don't look for documentation for a class named "Excluder". That's just what I call ObjectMarshallers that exclude properties). In our domain, teachers aren't allowed to see a students' social security numbers and the client developer has no need for GORM's id and class attributes.
+```
+#!groovy
+JSON.excludeForTeachers(TestStudent, ['socialSecurityNumber', 'id', 'class'])
+```
 
-[Pygments]: http://www.pygments.org/
+Finally, we use this excluder (ObjectMarshaller) to instantiate a JSON converter that will only output the properties appropriate for teachers to see.
+```
+#!groovy
+def json, resultTeachersWillSee
 
+JSON.use('excludeForTeachers') {
+    json = new JSON(student)
+}
+resultTeachersWillSee = json.toString()
+```
 
-Here's an example of some Python code:
+Do something with the result...
+```
+#!groovy
+println resultTeachersWillSee
+```
 
+Outputs:
+```
+#!json
+{"firstName":"Tobias","gradePointAverage":3.6,"lastName":"Funke","studentID":"FS-210-7312"}
 ```
-#!python
 
-def wiki_rocks(text):
-    formatter = lambda t: "funky"+t
-    return formatter(text)
+### Multiple Named Excluders
+Create a bunch of excluders for different purposes/audiences.
+
+```
+#!groovy
+// Create
+JSON.excludeForTeachers(TestStudent, ['socialSecurityNumber', 'id', 'class'])
+JSON.excludeForOtherStudents(TestStudent, ['gradePointAverage', 'studentID', 
+    'socialSecurityNumber', 'id', 'class'])
+JSON.excludeForTestAdministrators(TestStudent, ['gradePointAverage', 
+    'socialSecurityNumber', 'id', 'class'])
+
+// Use
+JSON.use('excludeForTeachers') {
+    json = new JSON(student)
+}
+resultTeachersWillSee = json.toString()
+
+JSON.use('excludeForOtherStudents') {
+    json = new JSON(student)
+}
+resultOtherStudentsWillSee = json.toString()
+
+// We can also embed the excluder within use('deep') though it has no affect 
+// our simple TestStudent class.
+JSON.use('deep') {
+    JSON.use('excludeForTestAdministrators') {
+        json = new JSON(student)
+        json.prettyPrint = false
+        resultTestAdministratorsWillSee = json.toString()
+    }
+}
 ```
 
+## What problem does the plugin solve?
+
+The grails.converter.JSON class is powerful. That power comes at the cost of some complexity though. This plugin utilizes Groovy's meta-programming features to simplify the common task of excluding arbitrary properties from the JSON payload at run-time. The most common use for this plugin will be to simply ensure that the 'id' and 'class' properties added by GORM are not included in the JSON string. Basically, it allows you to tackle this common task using expressive, domain specific language, quickly and simply. It also makes it simple to determine at run-time which properties to exclude.
+
+### Other resources and discussion surrounding this issue
+
+[GRAILS-5791: "Create a way to easily exclude properties from Serialization when using the XML or JSON converters"](http://jira.grails.org/browse/GRAILS-5791)
+
+[Official Grails Documentation: Using Named Configurations for Object Marshallers](http://grails.org/doc/2.3.x/guide/webServices.html#namedObjectMarshallers)
+
+[StackOverflow: "grails.converters.JSON except few properties"](http://stackoverflow.com/questions/5936300/grails-converters-json-except-few-properties)
 
-You can check out the source of this page to see how that's done, and make sure to bookmark [the vast library of Pygment lexers][lexers], we accept the 'short name' or the 'mimetype' of anything in there.
-[lexers]: http://pygments.org/docs/lexers/
+[Rendering JSON in Grails: Part 3 Customise your JSON with Object Marshallers](http://manbuildswebsite.com/2010/02/15/rendering-json-in-grails-part-3-customise-your-json-with-object-marshallers/)
 
+### Improvements to be made
+* Infer the class type of the target object rather than requiring it to be passed in. This is a challenge since the paradigm is based on static methods.
+* Stacking named marshallers to apply multiple marshallers to a single converter instance
+* Instance level ObjectMarshalling
 
-Have fun!
+##Conclusion
+This is my first grails plugin. I hope you find it useful. I'm three weeks new to Groovy and Grails, and those three weeks have been spent reading related books and staying productive at work. I welcome any suggestions/code contributions that would improve the plugin until Graeme and team are able to make updates to the JSON converter class to support this type of behavior.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.