CSC/ECE 517 Fall 2012/ch2b 2w59 bc: Difference between revisions

From Expertiza_Wiki
Jump to navigation Jump to search
m (Created page with "=Decorator Directory= ==General Resources== ==Ruby== ==Java & C#==")
 
 
(33 intermediate revisions by 2 users not shown)
Line 2: Line 2:


==General Resources==
==General Resources==
===Overview of the Pattern===
Wikipedia<ref name="wikipedia">http://en.wikipedia.org/wiki/Decorator_pattern - 2012</ref> and dofactory<ref name="dofactory">http://www.dofactory.com/Patterns/PatternDecorator.aspx - 2001 - 2012</ref> provide solid explanations of the Decorator Pattern. dofactory<ref name="dofactory"/> is much more concise than Wikipedia<ref name="wikipedia"/>. It is a good resource for quickly viewing the definition and participants of the pattern. Wikipedia<ref name="wikipedia"/>, on the other hand, is much more verbose, but goes into the motivation for the pattern and discusses use of the patterns in several languages at a high level.
If you understand Java (or a Java like language), javapapers<ref name="javapapers">http://javapapers.com/design-patterns/decorator-pattern/ - 2011</ref> is a good page that gives a basic overview of the pattern through the presentation of a concrete example. There are other Java resources and resources for other languages that are similar below.
===UML===
Understand the UML diagram for the Decorator pattern can help you understand the purpose of the Decorator pattern, the classes involved and how they interact with each other. UML is not programming language specific, so you should be able look at the UML diagram in any of the resources that have them on this page, regardless of what languages you know.
Wikipedia<ref name="wikipedia"/> and dofactory<ref name="dofactory"/> both provide UML diagrams of the Decorator Pattern concept. For UML diagrams of concrete examples, javapapers<ref name="javapapers"/> provides an Ice Cream example and Head First Design Patterns<ref name="head_first">https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf - 2004 - 2008</ref> provides a couple as well, but it is a very long read. Many of the language specific resources listed later in this article also provide UML diagrams for their concrete examples/implementations.
===Summary===
For a general overview and UML diagrams of the Decorator design pattern, we recommend:
*[http://en.wikipedia.org/wiki/Decorator_pattern Wikipedia]
*[http://www.dofactory.com/Patterns/PatternDecorator.aspx dofactory]
*[http://javapapers.com/design-patterns/decorator-pattern/ javapapers]
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]


==Ruby==
==Ruby==
Understanding the general concepts behind using the Decorator pattern would be the first step for any language implementation. The next step is usually finding examples that show how the pattern can be used, possibly by language. Here we will look at sources that give useful examples for understanding how to implement the Decorator pattern in Ruby. It is also worth noting that all references cited in this wiki are useful for understanding the pattern in general, despite the language that may be used in the examples.
The most popular example used to explain the Decorator pattern in Ruby is an example involving a Coffee class, of which there are various subclasses of coffee that can have various additional ingredients (milk, sugar, etc.). For many of the sites, they mentioned using the "Head First Design Patterns" book as a source, so of course we recommend the same <ref name="head_first"></ref>. The biggest disadvantage to using this resource is that it is a part of a textbook so is rather lengthy. There are a variety of sites devoted to explaining this pattern (most of which use the Coffee example) but a few stood out as especially useful in various ways. One of the better resources for any project is someone that has used the pattern before and blogs are a great place to start. One blog in particular gives a great explanation of the Decorator pattern being used in the Coffee example <ref name="8lines"> http://lukeredpath.co.uk/blog/decorator-pattern-with-ruby-in-8-lines.html - 2006</ref>. This is one of the sources that explicitly mentioned using the "Head First Design Patterns" book, so it may be easy to use these resources in parallel.
Another useful resource for implementing the Decorator pattern in Ruby written by another developer is on the site Programming = Fun <ref name="decorators"> http://kresimirbojcic.com/2011/12/01/decorators-in-ruby.html -2011 </ref>. One advantage this source has over the previous is that it is more up to date so it is less likely that there will be conflicting information with current knowledge and technology. This site uses the same coffee example but does not mention using the book so this may threaten how valid their interpretation is. Although they are both also about the same length in terms of words and code snippets, it seems that this one is more detailed in explaining what they did and why as they present the relevant code snippets. A disadvantage to using either of these resources is that if you are looking for variety or different ways of implementing the pattern they do not offer this information.
If you are not sure how you want to use the Decorator but you believe you may want to use it, then the explanations given on Thoughtbot might be useful <ref name="alternatives"> http://robots.thoughtbot.com/post/14825364877/evaluating-alternative-decorator-implementations-in - 2011 </ref>. This source also uses the Coffee example, however looks at various ways of implementing the coffee example using the Decorator pattern. This source may be the most useful for examples because of the fact that it includes the example from the "Head First Design Patterns" book but also includes other alternatives that most other sites do not consider or explain. This source also has the advantage that is uses a good mix of textual explanations and code snippets to get the concepts across. A disadvantage is that if you are wanting more in depth explanations on the alternative methods they describe it may be difficult to find other sources that use similar examples but also explain them in more detail.
===Summary===
For Ruby resources, we recommend:
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]
*[http://kresimirbojcic.com/2011/12/01/decorators-in-ruby.html  Decorators]
*[http://robots.thoughtbot.com/post/14825364877/evaluating-alternative-decorator-implementations-in  Alternatives]
*[http://lukeredpath.co.uk/blog/decorator-pattern-with-ruby-in-8-lines.html Confessions of Ruby Programmer]


==Java & C#==
==Java & C#==
There are a variety of resources available for learning how to use the Decorator pattern in Java and C#. We group these together as they are syntactically similar languages. One of the most popular references for learning about Design Patterns in Java is the book "Head First Design Patterns"<ref name="head_first"/>; in this book an in-depth explanation of the Decorator Pattern can be found. This is probably more popular because of how in-depth its explanation is of the design pattern, using diagrams and an ongoing coding example. It is also worth noting the the coding example used in this book (and a number of resources dedicated to the Decorator pattern) is a Coffee class where you wish to "decorate" your coffee with different additional ingredients. If you are really interested in learning the ins and outs of the Decorator pattern and do not mind a lengthy read, this is the best reference to use in regard to learning and understanding how to use this pattern.
If you are interested in learning about the Decorator pattern for Java and/or C# but do not have enough time or energy to read the chapter in the "Head First Design Patterns"<ref name="head_first"/> book, there are other resources that can be used to achieve an understanding but are less textual. Most of the resources that are not highly verbose use an over-arching example to explain the pattern. A good and simple resource for learning how to use the Decorator pattern in Java can be found on the site SourceMaking, a site devoted to teaching IT concepts such as Design Patterns and UML to professional developers<ref name="sourcemaking"> http://sourcemaking.com/design_patterns/decorator - 2012?</ref>. This resource includes a number of Java (and C#) examples meant to explain the usage of the pattern as well as textual explanations if needed. An advantage to using this resource is that it uses less text and more examples to show how the Decorator pattern can be used. It is also helpful that this site has multiple examples that can help increase understanding through reinforcement and multiple viewpoints (and languages). A disadvantage to using this site is that all of the examples are general examples using the pattern as opposed to real life situations or scenarios (like the Coffee example). If it is more useful for you to have a more in-depth walk through of a general example, then using the "Decorator Pattern by Example" page may be more helpful <ref name="dpexample"> http://www.agiledeveloper.com/articles/DecoratorByExample.pdf - ? </ref>
Some sites use over-arching real life examples to explain the Decorator pattern and its usage. The most popular of these examples (in any language) is the Coffee class mentioned previously, however there are other examples based on real life scenarios and situations that can relay the same information. One that seems to be useful in conveying the idea behind the Decorator pattern is using the pattern to report sports statistics for a given team. One site uses the example of a developer hired to create software that reports Soccer sports statistics <ref name="soccer">http://blog.image0.com/c-2/design-patterns-series-the-decorator-pattern-with-a-real-world-soccer-example/ - 2012 </ref>. This site uses a mix of textual explanations and examples to explain the pattern. One advantage to using this site is that it is relatively short and includes a real world example. It also provides the code in a way that would make it simple to attempt to run it yourself and see how it works. A disadvantage for this resource is that it does not break down exactly how it got all of its code so it may be difficult to understand how to get going on your own using your own "problem".
Although most examples for this pattern focus on other usages, it is possible to use the Decorator pattern with GUIs (Graphical User Interfaces). A useful example for understanding this usage can be found on OODesign.com <ref name="gui">http://www.oodesign.com/decorator-pattern-gui-example-java-sourcecode.html - ?</ref>. This site uses code and UML diagrams to explain the usage of Decorator when implementing GUIs. There are small textual explanations in between code snippets but the bulk of the page is code. This site is useful because it offers code that can easily be tested and/or modified if needed to gain a better understanding. Another advantage is that there is not much that has to be read. A disadvantage is that if the code given is not similar to what you are trying to achieve it may be difficult to understand whether you need to be using the Decorator pattern for you particular GUI; outside sources may be needed for this understanding.
===Summary===
For Java and C# resources, we recommend:
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]
*[http://sourcemaking.com/design_patterns/decorator SourceMaking]
*[http://blog.image0.com/c-2/design-patterns-series-the-decorator-pattern-with-a-real-world-soccer-example/ blog.image0]
*[http://www.oodesign.com/decorator-pattern-gui-example-java-sourcecode.html OODesign]
==Directory==
*[http://en.wikipedia.org/wiki/Decorator_pattern Wikipedia - Decorator Pattern]
**Summary: Typical Wiki page
**Pro: Provides background, motivation and a good overview of the pattern, as well as some high level examples.
**Con: Wikipedia can be fairly difficult to follow sometimes and this article is not much of an exception (also, Wikipedia's credibility is debated).
*[http://www.dofactory.com/Patterns/PatternDecorator.aspx dofactory - Decorator Design Pattern]
**Summary: Quick reference of UML and participants
**Pro: Provides a quick definition, list of participants and abstract UML diagram.
**Con: Not much of an explanation - just good for referencing.
*[http://javapapers.com/design-patterns/decorator-pattern/ javapapers - Decorator Design Pattern]
**Summary: Ice Cream example in Java
**Pro: Provides a short overview of the pattern as well as a good concrete example with UML and Java code.
**Con: The concrete example is a good start, but it may not be real-world enough to provide a complete understand.
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]
**Summary: Textbook chapter
**Pro: Is a excerpt from a commercial textbook, so the source is extremely credible and provides an in depth explanation of the design pattern complete with UML and a concrete example.
**Con: The textbook does not appear too professional and provides a lot of background that isn't really necessary for understanding the pattern. This is very long read.
*[http://lukeredpath.co.uk/blog/decorator-pattern-with-ruby-in-8-lines.html confessions of a ruby programmer]
**Summary: Coffee example in Ruby with lots of code as well as discussion.
**Pro: Lots of source code to look through and a helpful overview of Decorator
**Con: Provides a common implementation - nothing outside of the box.
*[http://kresimirbojcic.com/2011/12/01/decorators-in-ruby.html Decorators in Ruby]
**Summary: Another coffee example in Ruby with lots of code and discussion.
**Pro: Also has lots of source code to look through and help with Decorator implementations in Ruby.
**Con: Also provides a common implementation - nothing outside of the box.
*[http://robots.thoughtbot.com/post/14825364877/evaluating-alternative-decorator-implementations-in Evaluating alternative Decorator implementations in Ruby]
**Summary: Provides an overview of the normal implementation and some alternative implementations of Decorator in Ruby.
**Pro: Lots of code samples on various implementations. This is a more advanced resource than just understanding the basics of the pattern.
**Con: A bit lengthier, but that comes with the advanced nature of the article.
*[http://sourcemaking.com/design_patterns/decorator SourceMaking - Decorator Design Pattern]
**Summary: Window example with Java snippets, checklist and rules of thumb.
**Pro: This page presents an interesting concrete example with UML diagrams and code snippets. At the end, it covers a checklist for using the Decorator pattern as well as some rules of thumb.
**Con: The code provided in this resource are just snippets, not a full example.
*[https://docs.google.com/viewer?url=http%3A%2F%2Fwww.agiledeveloper.com%2Farticles%2FDecoratorByExample.pdf Decorator Pattern by Example]
**Summary: Scholarly paper discussing the usage of Decorator pattern Java with a Registration example.
**Pro: Very detailed and complete code.
**Con: Longer and very technical, but this comes with the advanced nature/scholarly paper nature.
*[http://blog.image0.com/c-2/design-patterns-series-the-decorator-pattern-with-a-real-world-soccer-example/ Design Pattern Series]
**Summary: Covers Decorator pattern in C# with a soccer statistics example.
**Pro: Plenty of code with a real world example and discusses implementation quite well.
**Con: Doesn't go into too much detail with the concept and how they developed their code.
*[http://www.oodesign.com/decorator-pattern-gui-example-java-sourcecode.html OODesign]
**Summary: Code intensive GUI example in Java
**Pro: The UML diagram is nice and the code is quite complete. The concrete example is applicable to the real world.
**Con: The page does not provide too much explanation, mainly just a code sample.
==References==
<references/>

Latest revision as of 21:35, 16 November 2012

Decorator Directory

General Resources

Overview of the Pattern

Wikipedia<ref name="wikipedia">http://en.wikipedia.org/wiki/Decorator_pattern - 2012</ref> and dofactory<ref name="dofactory">http://www.dofactory.com/Patterns/PatternDecorator.aspx - 2001 - 2012</ref> provide solid explanations of the Decorator Pattern. dofactory<ref name="dofactory"/> is much more concise than Wikipedia<ref name="wikipedia"/>. It is a good resource for quickly viewing the definition and participants of the pattern. Wikipedia<ref name="wikipedia"/>, on the other hand, is much more verbose, but goes into the motivation for the pattern and discusses use of the patterns in several languages at a high level.

If you understand Java (or a Java like language), javapapers<ref name="javapapers">http://javapapers.com/design-patterns/decorator-pattern/ - 2011</ref> is a good page that gives a basic overview of the pattern through the presentation of a concrete example. There are other Java resources and resources for other languages that are similar below.

UML

Understand the UML diagram for the Decorator pattern can help you understand the purpose of the Decorator pattern, the classes involved and how they interact with each other. UML is not programming language specific, so you should be able look at the UML diagram in any of the resources that have them on this page, regardless of what languages you know.

Wikipedia<ref name="wikipedia"/> and dofactory<ref name="dofactory"/> both provide UML diagrams of the Decorator Pattern concept. For UML diagrams of concrete examples, javapapers<ref name="javapapers"/> provides an Ice Cream example and Head First Design Patterns<ref name="head_first">https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf - 2004 - 2008</ref> provides a couple as well, but it is a very long read. Many of the language specific resources listed later in this article also provide UML diagrams for their concrete examples/implementations.

Summary

For a general overview and UML diagrams of the Decorator design pattern, we recommend:

Ruby

Understanding the general concepts behind using the Decorator pattern would be the first step for any language implementation. The next step is usually finding examples that show how the pattern can be used, possibly by language. Here we will look at sources that give useful examples for understanding how to implement the Decorator pattern in Ruby. It is also worth noting that all references cited in this wiki are useful for understanding the pattern in general, despite the language that may be used in the examples.

The most popular example used to explain the Decorator pattern in Ruby is an example involving a Coffee class, of which there are various subclasses of coffee that can have various additional ingredients (milk, sugar, etc.). For many of the sites, they mentioned using the "Head First Design Patterns" book as a source, so of course we recommend the same <ref name="head_first"></ref>. The biggest disadvantage to using this resource is that it is a part of a textbook so is rather lengthy. There are a variety of sites devoted to explaining this pattern (most of which use the Coffee example) but a few stood out as especially useful in various ways. One of the better resources for any project is someone that has used the pattern before and blogs are a great place to start. One blog in particular gives a great explanation of the Decorator pattern being used in the Coffee example <ref name="8lines"> http://lukeredpath.co.uk/blog/decorator-pattern-with-ruby-in-8-lines.html - 2006</ref>. This is one of the sources that explicitly mentioned using the "Head First Design Patterns" book, so it may be easy to use these resources in parallel.

Another useful resource for implementing the Decorator pattern in Ruby written by another developer is on the site Programming = Fun <ref name="decorators"> http://kresimirbojcic.com/2011/12/01/decorators-in-ruby.html -2011 </ref>. One advantage this source has over the previous is that it is more up to date so it is less likely that there will be conflicting information with current knowledge and technology. This site uses the same coffee example but does not mention using the book so this may threaten how valid their interpretation is. Although they are both also about the same length in terms of words and code snippets, it seems that this one is more detailed in explaining what they did and why as they present the relevant code snippets. A disadvantage to using either of these resources is that if you are looking for variety or different ways of implementing the pattern they do not offer this information.

If you are not sure how you want to use the Decorator but you believe you may want to use it, then the explanations given on Thoughtbot might be useful <ref name="alternatives"> http://robots.thoughtbot.com/post/14825364877/evaluating-alternative-decorator-implementations-in - 2011 </ref>. This source also uses the Coffee example, however looks at various ways of implementing the coffee example using the Decorator pattern. This source may be the most useful for examples because of the fact that it includes the example from the "Head First Design Patterns" book but also includes other alternatives that most other sites do not consider or explain. This source also has the advantage that is uses a good mix of textual explanations and code snippets to get the concepts across. A disadvantage is that if you are wanting more in depth explanations on the alternative methods they describe it may be difficult to find other sources that use similar examples but also explain them in more detail.

Summary

For Ruby resources, we recommend:

Java & C#

There are a variety of resources available for learning how to use the Decorator pattern in Java and C#. We group these together as they are syntactically similar languages. One of the most popular references for learning about Design Patterns in Java is the book "Head First Design Patterns"<ref name="head_first"/>; in this book an in-depth explanation of the Decorator Pattern can be found. This is probably more popular because of how in-depth its explanation is of the design pattern, using diagrams and an ongoing coding example. It is also worth noting the the coding example used in this book (and a number of resources dedicated to the Decorator pattern) is a Coffee class where you wish to "decorate" your coffee with different additional ingredients. If you are really interested in learning the ins and outs of the Decorator pattern and do not mind a lengthy read, this is the best reference to use in regard to learning and understanding how to use this pattern.

If you are interested in learning about the Decorator pattern for Java and/or C# but do not have enough time or energy to read the chapter in the "Head First Design Patterns"<ref name="head_first"/> book, there are other resources that can be used to achieve an understanding but are less textual. Most of the resources that are not highly verbose use an over-arching example to explain the pattern. A good and simple resource for learning how to use the Decorator pattern in Java can be found on the site SourceMaking, a site devoted to teaching IT concepts such as Design Patterns and UML to professional developers<ref name="sourcemaking"> http://sourcemaking.com/design_patterns/decorator - 2012?</ref>. This resource includes a number of Java (and C#) examples meant to explain the usage of the pattern as well as textual explanations if needed. An advantage to using this resource is that it uses less text and more examples to show how the Decorator pattern can be used. It is also helpful that this site has multiple examples that can help increase understanding through reinforcement and multiple viewpoints (and languages). A disadvantage to using this site is that all of the examples are general examples using the pattern as opposed to real life situations or scenarios (like the Coffee example). If it is more useful for you to have a more in-depth walk through of a general example, then using the "Decorator Pattern by Example" page may be more helpful <ref name="dpexample"> http://www.agiledeveloper.com/articles/DecoratorByExample.pdf - ? </ref>

Some sites use over-arching real life examples to explain the Decorator pattern and its usage. The most popular of these examples (in any language) is the Coffee class mentioned previously, however there are other examples based on real life scenarios and situations that can relay the same information. One that seems to be useful in conveying the idea behind the Decorator pattern is using the pattern to report sports statistics for a given team. One site uses the example of a developer hired to create software that reports Soccer sports statistics <ref name="soccer">http://blog.image0.com/c-2/design-patterns-series-the-decorator-pattern-with-a-real-world-soccer-example/ - 2012 </ref>. This site uses a mix of textual explanations and examples to explain the pattern. One advantage to using this site is that it is relatively short and includes a real world example. It also provides the code in a way that would make it simple to attempt to run it yourself and see how it works. A disadvantage for this resource is that it does not break down exactly how it got all of its code so it may be difficult to understand how to get going on your own using your own "problem".

Although most examples for this pattern focus on other usages, it is possible to use the Decorator pattern with GUIs (Graphical User Interfaces). A useful example for understanding this usage can be found on OODesign.com <ref name="gui">http://www.oodesign.com/decorator-pattern-gui-example-java-sourcecode.html - ?</ref>. This site uses code and UML diagrams to explain the usage of Decorator when implementing GUIs. There are small textual explanations in between code snippets but the bulk of the page is code. This site is useful because it offers code that can easily be tested and/or modified if needed to gain a better understanding. Another advantage is that there is not much that has to be read. A disadvantage is that if the code given is not similar to what you are trying to achieve it may be difficult to understand whether you need to be using the Decorator pattern for you particular GUI; outside sources may be needed for this understanding.

Summary

For Java and C# resources, we recommend:

Directory

  • Wikipedia - Decorator Pattern
    • Summary: Typical Wiki page
    • Pro: Provides background, motivation and a good overview of the pattern, as well as some high level examples.
    • Con: Wikipedia can be fairly difficult to follow sometimes and this article is not much of an exception (also, Wikipedia's credibility is debated).
  • dofactory - Decorator Design Pattern
    • Summary: Quick reference of UML and participants
    • Pro: Provides a quick definition, list of participants and abstract UML diagram.
    • Con: Not much of an explanation - just good for referencing.
  • javapapers - Decorator Design Pattern
    • Summary: Ice Cream example in Java
    • Pro: Provides a short overview of the pattern as well as a good concrete example with UML and Java code.
    • Con: The concrete example is a good start, but it may not be real-world enough to provide a complete understand.
  • Head First Design Patterns
    • Summary: Textbook chapter
    • Pro: Is a excerpt from a commercial textbook, so the source is extremely credible and provides an in depth explanation of the design pattern complete with UML and a concrete example.
    • Con: The textbook does not appear too professional and provides a lot of background that isn't really necessary for understanding the pattern. This is very long read.
  • confessions of a ruby programmer
    • Summary: Coffee example in Ruby with lots of code as well as discussion.
    • Pro: Lots of source code to look through and a helpful overview of Decorator
    • Con: Provides a common implementation - nothing outside of the box.
  • Decorators in Ruby
    • Summary: Another coffee example in Ruby with lots of code and discussion.
    • Pro: Also has lots of source code to look through and help with Decorator implementations in Ruby.
    • Con: Also provides a common implementation - nothing outside of the box.
  • Evaluating alternative Decorator implementations in Ruby
    • Summary: Provides an overview of the normal implementation and some alternative implementations of Decorator in Ruby.
    • Pro: Lots of code samples on various implementations. This is a more advanced resource than just understanding the basics of the pattern.
    • Con: A bit lengthier, but that comes with the advanced nature of the article.
  • SourceMaking - Decorator Design Pattern
    • Summary: Window example with Java snippets, checklist and rules of thumb.
    • Pro: This page presents an interesting concrete example with UML diagrams and code snippets. At the end, it covers a checklist for using the Decorator pattern as well as some rules of thumb.
    • Con: The code provided in this resource are just snippets, not a full example.
  • Decorator Pattern by Example
    • Summary: Scholarly paper discussing the usage of Decorator pattern Java with a Registration example.
    • Pro: Very detailed and complete code.
    • Con: Longer and very technical, but this comes with the advanced nature/scholarly paper nature.
  • Design Pattern Series
    • Summary: Covers Decorator pattern in C# with a soccer statistics example.
    • Pro: Plenty of code with a real world example and discusses implementation quite well.
    • Con: Doesn't go into too much detail with the concept and how they developed their code.
  • OODesign
    • Summary: Code intensive GUI example in Java
    • Pro: The UML diagram is nice and the code is quite complete. The concrete example is applicable to the real world.
    • Con: The page does not provide too much explanation, mainly just a code sample.

References

<references/>