An Interface describes a set of functions and events in a generic way; without providing an implementation. Components then implement those interfaces by providing executable code for the functions and firing the events. See Components, Component Events. In this way, Interfaces are abstractions of a problem space and, in fact, an interface is an abstract type. For UJML, Interfaces are the only way you can add a new data type to the language. See reference data type, Interface Types. 

A well-designed Interface consists of a closely related set of functions and events which provide some specific service. It should be clean and not include anything not directly related to that service. Because a component may implement more than one Interface, Interfaces may build upon one another to provide higher-level abstractions in a design. See Components and Object Oriented Programming.

Interfaces are declared using one or more interface elements contained by an interfaces element. Each interface element may contain a functions element and/or an events element. See interfaces element, interface element, functions element, events element. 

A functions element in an Interface contains zero or more function elements, which define the functions provided by the Interface. These definitions must not contain a script element or a return element. In essence the function is 'empty', providing just the name, return type and parameters. See function element. 

A events element in an Interface contains zero or more event elements, which define the events provided by the Interface. These definitions must not contain a script element. Like a function in an Interface, the event is 'empty', providing just the name and parameters. See event element. 

A simple interface definition with one function (foo) and one UJML event (bar) would look like this:

<ujml>
   <interfaces>
      <interface name="IExample">
         <functions>
            <function name="foo" type="int">
               <parameters>
                  <var name="x" type="int">
                  <var name="y" type="int">
                  <var name="name" type="string">
               </parameters>
            </function>
         </functions>
         <events>
            <event name="bar">
               <parameters>
                  <var name="count" type="int">
                  <var name="name" type="string">
               </event>
            </function>
         </events>
      </interface>
   </interfaces>
</ujml>

You can declare an interface in the same file as a component that implements it or as an application that uses it. Interfaces may also be declared in separate UJML files and included into component and application files with an include element inside of an interfaces element. See Interface Declaration Files, include element, interfaces element. Interface files may contain one to many interface declarations.

Public functions of a component must implement the members of a declared interface. See Components. The particular member of an interface implemented by a component function is indicated in the component function name using the interface name and member name in 'dot notation'. For example 'InterfaceName.memberName'. 

A component may implement members of more than one interface. Which interfaces a component implements is determined by the components declared inside of an interfaces element contained by the component element. See interfaces element. Inside of the interfaces element are one or more interface elements, each specifying an interface name and an access level of 'import' or 'export'. See interfaces element, interface element. Imported interfaces may be accessed by code in the component, but not exposed through public functions. Exported interfaces are exposed via public functions 

Note: All members of an exported interface must be exposed via the public functions of a component or an error will occur at compile time. 

Forward declarations 

If an Interface declaration contains references to other interface types (as return or parameter types) those types must be declared first or a compile error will result. See Interface Types. In cases where two classes refer to each other you must place one of them first, so UJML allows you to do a 'forward declaration' by creating an 'empty' named interface and then declaring the actual interface later. 

For example:

<!-- Forward declaration -->
<interface "IChild"/>

<!-- Parent declaration -->
<interface name="IParent">
    <functions>
        <function name="makeChild" type="IChild"/>
    </functions>
</interface>

<!-- Child declaration -->
<interface name="IChild">
    <functions>
        <function name="setParent" type="void">
            <parameters>
                <var name="parent" type="IParent"/>
            </parameters>
        </function>
    </functions>
</interface>

Two modes for the interfaces element 

The interfaces element has two different modes. When it's parent element is the ujml element it is used to declare or include an interface into the ujml file. When its parent element is an application, partition, or component element it is used to indicate what interfaces that element imports or exports.

Before a module (a component, partition, or application element) can create reference variables of a specific interface type the module must indicate it is using the interface by declaring the interface inside the module element with a access attribute value of 'import'. 

For example:

<interfaces>
    <interface name="IFoo" access="import"/>
</interfaces>

Before a component module can implement the functions of a specific interface type the component must indicate it is implementing the interface by declaring the interface inside the module element with a access attribute value of 'export'. 

For example:

<interfaces>
    <interface name="IFoo" access="export"/>
</interfaces>

The following example shows how to include two interface declarations. It is part of the life.ujml sample.

<interfaces>
    <include interface="ILifeGrid" file="ilife.ujmi"/>
    <include interface="ILifeMenu" file="ilife.ujmi"/>
</interfaces>

The following example shows how to import the two interface declarations included above. It is part of the life.ujml sample.

<interfaces>
    <interface name="ILifeGrid" access="import"/>
    <interface name="ILifeMenu" access="import"/>
</interfaces>

The following example shows how to export two interface declarations. It is part of the animal.ujml sample.

<interfaces>
    <interface name="IThing" access="export"/>
    <interface name="IAnimal" access="export"/>
</interfaces>

The following example shows two complete interface declarations in a single Interface file. It is part of the ithings.ujmi sample.

<interface name="IThing">
    <functions>
        <!--
            Gets the name of the thing.
        -->
        <function name="getName" type="string" />
        <!--
            Gets a description of the thing.
        -->
        <function name="getDescription" type="string" />
        <!--
            Gets the image URL of the thing.
        -->
        <function name="getImageName" type="string" />
    </functions>
</interface>
<interface name="IUnknown">
    <functions>
        <!--
           Initializes the thing.
        -->
        <function name="init" type="void">
            <parameters>
                <var name="name" type="string"/>
                <var name="description" type="string"/>
                <var name="imgName" type="string"/>
            </parameters>
        </function>
    </functions>
</interface>

The following example shows a forward declaration. It is part of the timer.ujml sample.

<interfaces>
    <interface name="ITimerListener"/><!-- Forward declaration. -->
    <include interface="ITimerSource" file="itimer.ujmi"/>
    <include interface="ITimerListener" file="itimer.ujmi"/>
</interfaces>

Components and Object Oriented Programming, Component Events, Components and Object Oriented Programming, Interface Declaration Files, reference, Interface Types, <interfaces>, <interface>, <include>, <functions>, <events>, life.ujml, animal.ujml, ithings.ujmi, timer.ujml