Package score.annotation

Annotation Type External

@Target(METHOD)
public @interface External

Annotation that can be used to indicate whether the method will be exposed externally.

In order for a method to be called from outside the contract (EOA or another contract), it needs to be annotated as External. The annotated methods will be registered on the exportable API list. Any attempt to call a non-external method from outside the contract will fail.

If the readonly element is specified and its value is true, i.e., @External(readonly=true), the method will have read-only access to the state DB.

NOTE: The special method, named fallback, cannot be annotated with @External. (i.e., fallback method cannot be specified in the transaction message as a callee method, and it can only be called via plain ICX transfer message.)

Parameter Type

A parameter type of an external method is

• a simple value type,
• a writable struct, or
• an array of a parameter type

Simple Value Type

A simple value type is

• A boolean, char, byte, short, int or long, or
• A byte[], A BigInteger, Address or String

Writable Struct

A type is writable struct if

• the type is a non-abstract class,
• the type has no constructor or public zero argument constructor and
• the type has a public non-static setter method of writable property type.

For example, the following type is a writable struct.

      class Person {
          public Person() {...}
          public String getName() {...}
          public void setName(String name) {...}
          public int getAge() {...}
          public void setAge(int age) {...}
      }
 

Writable Property

A type is writable property type if the type is

• A simple value type,
• A Boolean, Character, Byte, Short, Integer or Long,
• A writable struct type (recursion is not allowed), or
• An array of writable property

Return Type

A return type of an external method is

• void,
• A simple value type,
• A readable struct (regarded as a map),
• an array of a non-void return type (regarded as a list),
• List where each element is of a non-void return type or null, or
• Map where each key is of a String and each value is of a non-void return type or null.

Readable Struct

A type is readable struct if the type has a public non-static getter method of readable property type. For example, the following type is a readable struct.

      class Person {
          public String getName() {...}
          public int getAge() {...}
      }
 

Readable Property

A type is readable property type if the type is

• A simple value type
• A Boolean, Character, Byte, Short, Integer and Long,
• A readable struct type (recursion is not allowed in this case), or
• An array of readable property

Exception

If an external method is called by an external transaction or an internal transaction and the method throws an exception, the transaction fails. If the exception is an instance of UserRevertException or its subclass, the failure code is decided by the exception. Refer to UserRevertException for details. Otherwise, system code UnknownFailure(1) is used as the failure code.

See Also:

UserRevertException

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
boolean	readonly	The method will have read-only access to the state DB if this value is true.

Element Detail

readonly

boolean readonly

The method will have read-only access to the state DB if this value is true.

Default:

false