Annotations provided by Gosu

The Gosu language provides annotations that are defined in the gw.lang.* package. This package is always in scope, so the fully qualified annotation name is not required.

The information in annotations that provide documentation for a type appears in the Gosudoc HTML page for the type. For example, web service endpoints use the @Param, @Returns, and @Throws annotations to document their methods. Running the gwb gosudoc command generates a Gosudoc HTML page that contains the information from the annotations.

The following table lists the general annotations:

Annotation	Description	Usage limits	Parameters
`@AutoCreate`	Annotates a property to indicate that if the property is null and referenced on the left hand side of an assignment statement, a non-null value is automatically created for it before continuing the evaluation of the left hand side of the assignment. In the following example, if `Address` is null, a new `Address` entity instance is created and `CA` is assigned to its `State` property. `person.Address.State = CA`	Methods only
`@AutoInsert`	Annotates a List property to indicate that if the property is null and referenced on the left hand side of an assignment statement, a non-null value is automatically added for it in the List before continuing the evaluation of the left hand side of the assignment. In the following example, `Hobbies` is a List property on `Person` and annotated with `@AutoInsert`. If the item at index 0 does not exist, an entity instance of the appropriate type is created and added to the list before `Name` is assigned. `person.Hobbies[0].Name = "Cycling"`	Methods only
`@DataType`	Annotates properties on objects so that appropriate field validators can be added. For example, the maximum number of characters for a first name can be specified.	Gosu objects and entities.	In Studio, see the type and parameter definitions described in the .dti files contained in the configuration > config > datatypes folder.
`@Deprecated`	Specifies that a class, method, constructor, or property will no longer be available in a future release. Begin rewriting code to avoid using this class, method, constructor, property, or function parameter.	Can appear anywhere, but only once for any specific class, method, constructor, property, or function argument.	A `String` warning to display if this deprecated class, method, or constructor is used. Note: Guidewire also provides a `@Deprecated` annotation that has the following parameters: `version:String` `value:String`
`@DoNotPublish`	Does not publicly publish the method to the external web service.
`@Exportable`	A platform-level annotation indicating that the tagged property is to be published as a public member of the declaring class.
`@Param`	Specifies the documentation of a parameter.	Methods only	`FieldName:String`: The name of the parameter. `FieldDescription:String`: Documentation in Javadoc format for the method’s parameter.
`@Params`	Adds an array of `@Param` annotations to a method. This annotation does not need to be explicitly declared because declaring a `@Param` annotation automatically creates a `@Params` annotation containing it.	Methods only
`@PublishedName`	Provides an alternative name to replace the declared name in code. Note: This annotation is deprecated
`@PublishInGosu`	Publishes the class in Gosu.	Classes only
`@Returns`	Specifies the documentation for the return result of the method.	Methods only, and only once for any specific method	`value:String`: Documentation in Javadoc format for the method’s return value.
`@ShortCircuitingProperty`	If a property getter has this annotation, member access expressions having null values will short-circuit to zero. Boolean properties currently always short-circuit to `false`. For certain properties, such as CoreIterableEnhancement.Count, null values that were permitted in previous versions of Java might now result in a NullPointerException being thrown.
`@SuppressWarnings`	Tells the compiler to suppress warnings. Gosu provides limited support for the Java annotation `@SuppressWarnings`.	Declarations of a type, function, property, constructor, field, or parameter. Note: Local variables do not support this annotation.	`value:String`: Indicates the warnings to suppress. Pass the argument `"all"` to suppress all warnings. Pass the argument `"deprecation"` to suppress deprecation warnings. For example, to suppress deprecation warnings in a Gosu class, on the line before the class declaration, add: `@SuppressWarnings("deprecation")`
`@Throws`	Specifies what exceptions might be thrown by this method.	Methods only	`ExceptionType:Class`: An exception type `ExceptionDescription:String`: A description in Javadoc format of the circumstances that cause the exception to be thrown, and how to interpret that exception.
`@UnstableAPI`	Marks a class, method, or parameter as unstable, indicating that the API might change in a future version and its use is to be avoided if possible.

Internal annotations

Some Gosu annotations are reserved for internal use. You might see internal annotations in Gosu code that is provided in the base configuration. These annotations are not supported for your use. The following table lists these internal annotations so you can understand how they are used.

Internal annotation	Description	Usage limits
`@Export`	Lets a class be visible and editable in Studio.	Classes only
`@ReadOnly`	Lets a class be visible in Studio, but not editable. Studio does not permit copying a read-only class into the configuration directory for modification.	Classes only

No support for Java 8 type annotations

The Gosu compiler permits method parameter annotations. However, Gosu does not support compiler or IDE behavior for the Java 8 Type annotations such as:

@m
@Nonnull
@ReadOnly
@Regex
@Tainted
@Untainted

Web service annotations

Several annotations related to publishing web services are available.

Examples

The following code uses several annotations:

package com.mycompany
uses java.lang.Exception

@WsiWebService 
class Test {
  @Param("Name", "The user's name. Must not be an empty string.")
  @Returns("A friendly greeting with the user's name")
  @Throws(Exception, "General exception if the string passed to us is empty or null")
  public function FriendlyGreeting(Name : String) : String { 

    if (Name == null or Name.length == 0) throw "Requires a non-empty string!"
    return "Hello, " + Name + "!"
  }
}

The following example specifies that a method is deprecated. A deprecated API component is temporarily available, but a future release will remove that component. Refactor any code that uses deprecated APIs to ensure that your code is compatible with future releases to simplify future upgrades.

package com.mycompany

class MyClass {

  @Deprecated("Don't use MyClass.myMethod(). Instead, use betterMethod().")
  public function myMethod() {print("Hello")}

  public function betterMethod() {print("Hello, World!")}
}

The annotation class that you are implicitly using must be in the current Gosu scope. You can ensure that it is in scope by fully qualifying the annotation. For example, if the SomeAnnotation annotation is defined within the package com.mycompany.some.package, specify the annotation as:

@com.mycompany.some.package.SomeAnnotation
class SomeClass {
  ...
}

Alternatively, import the package by using the Gosu uses statement and then use the annotation more naturally and concisely by using only its name:

uses com.mycompany.some.package.SomeAnnotation.*

@SomeAnnotation
class SomeClass {
  ...
}