        --------------------------------------------------
                      CodeNarc - Grails Rules
        --------------------------------------------------

Grails Rules  ("<rulesets/grails.xml>")
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* {GrailsDomainHasEquals} Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  <New in CodeNarc 0.15>

  Checks that Grails domain classes redefine <<<equals()>>>.

  Ignores classes annotated with <<<@EqualsAndHashCode>>> or <<<@Canonical>>>.


* {GrailsDomainHasToString} Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  <New in CodeNarc 0.15>

  Checks that Grails domain classes redefine <<<toString()>>>.

  Ignores classes annotated with <<<@ToString>>> or <<<@Canonical>>>.


* {GrailsPublicControllerMethod} Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  Rule that checks for public methods on Grails controller classes. Static methods are ignored.

  Grails controller actions and interceptors are defined as properties on the controller class.
  Public methods on a controller class are unnecessary. They break encapsulation and can
  be confusing.

*---------------------+----------------------------------------------------------------+------------------------+
| <<Property>>        | <<Description>>                                                | <<Default Value>>      |
*---------------------+----------------------------------------------------------------+------------------------+
| ignoreMethodNames   | Specifies one or more (comma-separated) method names that      | <<<null>>>             |
|                     | should be ignored (i.e., that should not cause a rule          |                        |
|                     | violation). The names may optionally contain wildcards (*,?).  |                        |
*---------------------+----------------------------------------------------------------+------------------------+

  This rule sets the default value of <<<applyToFilesMatching>>> to only match files
  under the 'grails-app/controllers' folder. You can override this with a different regular
  expression value if appropriate.

  This rule also sets the default value of <<<applyToClassNames>>> to only match class names
  ending in 'Controller'. You can override this with a different class name pattern
  (String with wildcards) if appropriate.


* {GrailsServletContextReference} Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  Rule that checks for references to the <<<servletContext>>> object from within Grails controller and
  taglib classes.

  This rule is intended as a "governance" rule to enable monitoring and controlling access to the
  <<<servletContext>>> from within application source code. Storing objects in the <<<servletContext>>>
  may inhibit scalability and/or performance and should be carefully considered. Furthermore, access to
  the <<<servletContext>>> is not synchronized, so reading/writing objects from the <<<servletConext>>>
  must be manually synchronized, as described in
  {{{http://www.amazon.com/Definitive-Grails-Second-Experts-Development/dp/1590599950}
  The Definitive Guide to Grails (2nd edition)}}.

  Note that this rule does not check for direct access to the <<<servletContext>>> from within GSP
  (Groovy Server Pages) files.

  Enabling this rule may make most sense in a team environment where team members exhibit a broad
  range of skill and experience levels. Appropriate <<<servletContext>>> access can be configured as exceptions
  to this rule by configuring either the <<<doNotApplyToFilenames>>> or
  <<<doNotApplyToFilesMatching>>> property of the rule. And, as always, it is easy to
  just {{{codenarc-configuring-rules.html#Turning_Off_A_Rule}turn off the rule}} if it does not
  make sense it your environment.

  This rule sets the default value of <<<applyToFilesMatching>>> to only match files
  under the 'grails-app/controllers' or 'grails-app/taglib' folders. You can override this
  with a different regular expression value if appropriate.


* {GrailsSessionReference} Rule (deprecated)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

*-------------------------------------------------------------------------------------------------+
| <<NOTE:>> This rule has been <<DEPRECATED>>, and disabled by default (i.e., by setting its
| <enabled> property to <false>). Please email the {{{mailto:codenarc-user@lists.sourceforge.net}CodeNarc User Mailing List}}
| if you have an opinion for/against deprecation and eventual removal of this rule.
*-------------------------------------------------------------------------------------------------+

  Rule that checks for references to the <<<session>>> object from within Grails controller and
  taglib classes.

  This rule is intended as a "governance" rule to enable monitoring and controlling access to the
  <<<session>>> from within application source code. Storing objects in the <<<session>>> may inhibit
  scalability and/or performance and should be carefully considered.

  Note that this rule does not check for direct access to the <<<session>>> from within GSP
  (Groovy Server Pages) files.

  Enabling this rule may make most sense in a team environment where team members exhibit a broad
  range of skill and experience levels. Appropriate <<<session>>> access can be configured as exceptions
  to this rule by configuring either the <<<doNotApplyToFilenames>>> or
  <<<doNotApplyToFilesMatching>>> property of the rule. And, as always, it is easy to
  just {{{codenarc-configuring-rules.html#Turning_Off_A_Rule}turn off the rule}} if it does not
  make sense it your environment.

  This rule sets the default value of <<<applyToFilesMatching>>> to only match files
  under the 'grails-app/controllers' or 'grails-app/taglib' folders. You can override this
  with a different regular expression value if appropriate.


* {GrailsStatelessService} Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  Checks for non-<<<final>>> fields on a Grails service class. Grails service classes are singletons by
  default, and so they should be reentrant. In most cases, this implies (or at least encourages)
  that they should be stateless.

  This rule ignores (i.e., does not cause violations for) the following:

  * All <<<final>>> fields (either instance or static). Note that fields that are <<<static>>> and non-<<<final>>>,
    however, do cause a violation.

  * Non-<<<static>>> properties (i.e., no visibility modifier specified) declared with <<<def>>>.

  * All classes annotated with the <<<@Immutable>>> transformation.
   See {{{http://groovy.codehaus.org/Immutable+transformation}http://groovy.codehaus.org/Immutable+transformation}}.

  * All fields annotated with the <<<@Inject>>> annotation.

  * All fields with names matching the <ignoreFieldNames> property.

  * All fields with types matching the <ignoreFieldTypes> property.

  []

  The <<<ignoreFieldNames>>> property of this rule is preconfigured to ignore the standard Grails
  service configuration field names ('scope', 'transactional') and the standard injected bean names
  ('dataSource', 'sessionFactory'), as well as all other field names ending with 'Service'.

*---------------------+----------------------------------------------------------------+---------------------------------------+
| <<Property>>        | <<Description>>                                                | <<Default Value>>                     |
*---------------------+----------------------------------------------------------------+---------------------------------------+
| ignoreFieldNames    | Specifies one or more (comma-separated) field names that       | <<<'dataSource,scope,sessionFactory,  |
|                     | should be ignored (i.e., that should not cause a rule          | transactional,*Service'>>>            |
|                     | violation). The names may optionally contain wildcards (*,?).  |                                       |
*---------------------+----------------------------------------------------------------+---------------------------------------+
| addToIgnoreFieldNames| Specifies one or more (comma-separated) field names to be     | <<<null>>>                            |
|                     | added to the <<<ignoreFieldNames>>> property value. This is a  |                                       |
|                     | special write-only property, and each call to                  |                                       |
|                     | <<<setAddIgnoreFieldNames()>>> adds to (rather than overwrites)|                                       |
|                     | the list of field names to be ignored.                         |                                       |
*-----------------------+----------------------------------------------------------------+-------------------------------------+
| ignoreFieldTypes    | Specifies one or more (comma-separated) field types that       | <<<null>>>                            |
|                     | should be ignored (i.e., that should not cause a rule          |                                       |
|                     | violation). The names may optionally contain wildcards (*,?).  |                                       |
|                     |                                                                |                                       |
*---------------------+----------------------------------------------------------------+---------------------------------------+

  This rule sets the default value of <<<applyToFilesMatching>>> to only match files under the
  'grails-app/services' folder. You can override this with a different regular expression value if appropriate.

  This rule also sets the default value of <<<applyToClassNames>>> to only match class names
  ending in 'Service'. You can override this with a different class name pattern (String with wildcards)
  if appropriate.


**  Notes
~~~~~~~~~~~~

  [[1]]  The <<<ignoreFieldTypes>>> property matches the field type name as indicated
  in the field declaration, only including a full package specification IF it is included in
  the source code. For example, the field declaration <<<BigDecimal value>>> matches
  an <<<ignoreFieldTypes>>> value of <<<BigDecimal>>>, but not
  <<<java.lang.BigDecimal>>>.

  [[2]]  There is one exception for the <<<ignoreFieldTypes>>> property: if the field is declared
  with a modifier/type of <<<def>>>, then the type resolves to <<<java.lang.Object>>>.

