//////////////////////////////////////////

  Licensed to the Apache Software Foundation (ASF) under one
  or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you under the Apache License, Version 2.0 (the
  "License"); you may not use this file except in compliance
  with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing,
  software distributed under the License is distributed on an
  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  KIND, either express or implied.  See the License for the
  specific language governing permissions and limitations
  under the License.

//////////////////////////////////////////

= Groovy Language Documentation
:doctype: book
ifdef::backend-pdf[:source-highlighter: rouge]

ifndef::reldir_root[]
:reldir_root: ../../../../../src/spec/doc
endif::[]
ifndef::reldir_console[]
:reldir_console: ../../../../../subprojects/groovy-console/src/spec/doc
endif::[]
ifndef::reldir_swing[]
:reldir_swing: ../../../../../subprojects/groovy-swing/src/spec/doc
endif::[]
ifndef::reldir_jmx[]
:reldir_jmx: ../../../../../subprojects/groovy-jmx/src/spec/doc
endif::[]

include::../../../../../src/spec/doc/core-introduction.adoc[]

== Groovy Language Specification

:core-domain-specific-languages:
:core-metaprogramming:
:core-object-orientation:
:core-operators:
:core-semantics:
:core-syntax:
:core-testing-guide:
:grape:
:groovy-ant-task:
:groovy-console:
:groovyc-ant-task:
:guide-integrating:
:jmx:
:tools-groovyc:
:xml-userguide:
:sql-userguide:

include::../../../../../src/spec/doc/core-syntax.adoc[leveloffset=+2]

include::../../../../../src/spec/doc/core-operators.adoc[leveloffset=+2]

include::../../../../../src/spec/doc/core-program-structure.adoc[leveloffset=+2]

include::../../../../../src/spec/doc/core-object-orientation.adoc[leveloffset=+2]

include::../../../../../src/spec/doc/core-closures.adoc[leveloffset=+2]

include::../../../../../src/spec/doc/core-semantics.adoc[leveloffset=+2]

== Tools

include::../../../../../src/spec/doc/tools-groovy.adoc[leveloffset=+2]

include::../../../../../src/spec/doc/tools-groovyc.adoc[leveloffset=+2]

include::../../../../../subprojects/groovy-groovysh/src/spec/doc/groovysh.adoc[leveloffset=+2]

include::../../../../../subprojects/groovy-console/src/spec/doc/groovy-console.adoc[leveloffset=+2]

include::../../../../../subprojects/groovy-groovydoc/src/spec/doc/groovydoc.adoc[leveloffset=+2]

include::../../../../../src/spec/doc/tools-ide.adoc[leveloffset=+2]

== User Guides

include::../../../../../src/spec/doc/core-getting-started.adoc[leveloffset=+2]

include::../../../../../src/spec/doc/core-differences-java.adoc[leveloffset=+2]

include::../../../../../src/spec/doc/core-gdk.adoc[leveloffset=+2]

include::../../../../../src/spec/doc/core-metaprogramming.adoc[leveloffset=+2]

include::../../../../../src/spec/doc/grape.adoc[leveloffset=+2]

include::../../../../../src/spec/doc/core-testing-guide.adoc[leveloffset=+2]

include::../../../../../src/spec/doc/performance-guide.adoc[leveloffset=+2]

include::../../../../../subprojects/groovy-json/src/spec/doc/json-userguide.adoc[leveloffset=+2]

include::../../../../../subprojects/groovy-sql/src/spec/doc/sql-userguide.adoc[leveloffset=+2]

include::../../../../../subprojects/groovy-ginq/src/spec/doc/ginq-userguide.adoc[leveloffset=+2]

include::../../../../../subprojects/groovy-xml/src/spec/doc/xml-userguide.adoc[leveloffset=+2]

include::../../../../../subprojects/groovy-yaml/src/spec/doc/yaml-userguide.adoc[leveloffset=+2]

include::../../../../../subprojects/groovy-toml/src/spec/doc/toml-userguide.adoc[leveloffset=+2]

include::../../../../../subprojects/groovy-contracts/src/spec/doc/contracts-userguide.adoc[leveloffset=+2]

=== Scripting Ant tasks

Groovy integrates very well with http://ant.apache.org[Apache Ant] thanks to <<antbuilder,AntBuilder>>.

include::../../../../../subprojects/groovy-ant/src/spec/doc/groovy-ant-task.adoc[leveloffset=+2]

include::../../../../../subprojects/groovy-ant/src/spec/doc/groovyc-ant-task.adoc[leveloffset=+2]

include::../../../../../subprojects/groovy-templates/src/spec/doc/template-engines.adoc[leveloffset=+2]

include::../../../../../subprojects/groovy-servlet/src/spec/doc/servlet-userguide.adoc[leveloffset=+2]

include::../../../../../src/spec/doc/guide-integrating.adoc[leveloffset=+2]

include::../../../../../src/spec/doc/core-domain-specific-languages.adoc[leveloffset=+2]

include::../../../../../subprojects/groovy-jmx/src/spec/doc/jmx.adoc[leveloffset=+2]

=== Creating Swing UIs

Creating Swing UIs is made easy thanks to the use of <<swingbuilder,SwingBuilder>>.

=== Security

Security is a complex and multi-faceted issue and needs to be addressed in a holistic way.
Groovy offers some features to improve security, but organisations
concerned about security should already be addressing other necessary aspects
such as network security, file-system security, operating sytem security, database security,
passwords and potentially encryption.

Also, since Groovy runs on the JDK and optionally uses other library dependencies,
users should ensure their JDK and all depdendencies are up to date with respect to
the latest security fixes.

With regard to security issues that may affect the Groovy project itself,
the project follows the Apache http://www.apache.org/security/committers.html[general guidelines for handling security vulnerabilities]. See also the project's
https://github.com/apache/groovy/security/policy[security policy] and list of
https://groovy-lang.org/security.html[past vulnerabilities].

By virtue of running on the JVM and following various Java conventions, Groovy programs
offer some of the same security features as Java programs, including:

* programs cannot access arbitrary memory locations
* final variables cannot be changed
* array bounds are checked
* class loaders perform bytecode verification when loading classes
* casting cannot be done to an incompatible class
* access is available to APIs for encryption and authentication

Special security support is provided through:

* gapi:groovy.lang.GroovyShell[], gapi:groovy.lang.GroovyClassLoader[] and other parts of the Groovy runtime fully support the Java security manager which allows you to sandbox script execution with a security policy. (Note: this funtionality might be scaled back in future Groovy versions or when running
on particular JDK versions in line with https://openjdk.java.net/jeps/411[JEP 411])
* gapi:org.codehaus.groovy.control.customizers.SecureASTCustomizer[]
secures source code by controlling what code constructs are permitted or prohibited in a code base
(or part of a code base)
* Default <<{xml-userguide}#processing-xml,XML processing>> has secure processing enabled and doctype definitions disabled
* Groovy's <<{sql-userguide}#processing-sql,SQL processing>> features provide support to guard against SQL injection
* Temporary directory creation protects against known security vulnerabilities such as privilege escalation if scripts are stored in operating system temp directories

include::../../../../../src/spec/doc/design-patterns-in-groovy.adoc[leveloffset=+2]

== Acknowledgements

include::../../../../../src/spec/doc/contributors.adoc[leveloffset=+2]

include::../../../../../src/spec/doc/license.adoc[leveloffset=+2]
