<commit_before><?xml version="1.0" encoding="UTF-8"?>
<section version="5.0"
         xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd http://www.w3.org/1999/xlink http://www.docbook.org/xml/5.0/xsd/xlink.xsd"
         xml:base="../" xmlns="http://docbook.org/ns/docbook"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:xs="http://www.w3.org/2001/XMLSchema"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:ns="http://docbook.org/ns/docbook">
  <title>Type Declaration</title>

  <figure>
    <title>meta_data</title>

    <mediaobject>
      <imageobject>
        <imagedata align="center"
                   fileref="images/LanguageReference/meta_data.png"
                   format="PNG"/>
      </imageobject>
    </mediaobject>
  </figure>

  <figure>
    <title>type_declaration</title>

    <mediaobject>
      <imageobject>
        <imagedata align="center"
                   fileref="images/LanguageReference/type_declaration.png"
                   format="PNG"/>
      </imageobject>
    </mediaobject>
  </figure>

  <para>Type declarations have two main goals in the rules engine: to allow
  the declaration of new types, and to allow the declaration of metadata for
  types.</para>

  <itemizedlist>
    <listitem>
      <para><emphasis role="bold">Declaring new types:</emphasis> Drools works
      out of the box with plain Java objects as facts. Sometimes, however,
      users may want to define the model directly to the rules engine, without
      worrying about creating models in a lower level language like Java. At
      other times, there is a domain model already built, but eventually the
      user wants or needs to complement this model with additional entities
      that are used mainly during the reasoning process.</para>
    </listitem>

    <listitem>
      <para><emphasis role="bold">Declaring metadata:</emphasis> facts may
      have meta information associated to them. Examples of meta information
      include any kind of data that is not represented by the fact attributes
      and is consistent among all instances of that fact type. This meta
      information may be queried at runtime by the engine and used in the
      reasoning process.</para>
    </listitem>
  </itemizedlist>

  <section>
    <title>Declaring New Types</title>

    <para>To declare a new type, all you need to do is use the keyword
    <literal>declare</literal>, followed by the list of fields, and the
    keyword <literal>end</literal>. A new fact must have a list of fields,
    otherwise the engine will look for an existing fact class in the classpath
    and raise an error if not found.</para>

    <example>
      <title>Declaring a new fact type: Address</title>

      <programlisting><emphasis role="bold">declare</emphasis> Address
   number : int
   streetName : String
   city : String
<emphasis role="bold">end</emphasis>
</programlisting>
    </example>

    <para>The previous example declares a new fact type called
    <code>Address</code>. This fact type will have three attributes:
    <code>number</code>, <code>streetName</code> and <code>city</code>. Each
    attribute has a type that can be any valid Java type, including any other
    class created by the user or even other fact types previously
    declared.</para>

    <para>For instance, we may want to declare another fact type
    <code>Person</code>:</para>

    <example>
      <title>declaring a new fact type: Person</title>

      <programlisting><emphasis role="bold">declare</emphasis> Person
    name : String
    dateOfBirth : java.util.Date
    address : Address
<emphasis role="bold">end</emphasis>
</programlisting>
    </example>

    <para>As we can see on the previous example, <code>dateOfBirth</code> is
    of type <code>java.util.Date</code>, from the Java API, while
    <code>address</code> is of the previously defined fact type
    Address.</para>

    <para>You may avoid having to write the fully qualified name of a class
    every time you write it by using the <literal>import</literal> clause, as
    previously discussed.</para>

    <example>
      <title>Avoiding the need to use fully qualified class names by using
      import</title>

      <programlisting><emphasis role="bold">import</emphasis> java.util.Date

<emphasis role="bold">declare</emphasis> Person
    name : String
    dateOfBirth : Date
    address : Address
<emphasis role="bold">end</emphasis></programlisting>
    </example>

    <para>When you declare a new fact type, Drools will, at compile time,
    generate bytecode that implements a Java class representing the fact type.
    The generated Java class will be a one-to-one Java Bean mapping of the
    type definition. So, for the previous example, the generated Java class
    would be:</para>

    <example>
      <title>generated Java class for the previous Person fact type
      declaration</title>

      <programlisting language="java">public class Person implements Serializable {
    private String name;
    private java.util.Date dateOfBirth;
    private Address address;

    // empty constructor
    public Person() {...}

    // constructor with all fields 
    public Person( String name, Date dateOfBirth, Address address ) {...}

    // if keys are defined, constructor with keys
    public Person( ...keys... ) {...}

    // getters and setters
    // equals/hashCode
    // toString
}
</programlisting>
    </example>

    <para>Since the generated class is a simple Java class, it can be used
    transparently in the rules, like any other fact.</para>

    <example>
      <title>Using the declared types in rules</title>

      <programlisting><emphasis role="bold">rule</emphasis> "Using a declared Type"
<emphasis role="bold">when</emphasis> 
    $p : Person( name == "Bob" )
<emphasis role="bold">then</emphasis>
    <emphasis>// Insert Mark, who is Bob's mate.</emphasis>
    Person mark = new Person();
    mark.setName("Mark");
    insert( mark );
<emphasis role="bold">end</emphasis>
</programlisting>
    </example>
  </section>

  <section>
    <title>Declaring Metadata</title>

    <para>Metadata may be assigned to several different constructions in
    Drools: fact types, fact attributes and rules. Drools uses the at sign
    ('@') to introduce metadata, and it always uses the form:</para>

    <programlisting>@<emphasis>metadata_key</emphasis>( <emphasis>metadata_value</emphasis> )</programlisting>

    <para>The parenthesized <emphasis>metadata_value</emphasis> is
    optional.</para>

    <para>For instance, if you want to declare a metadata attribute like<commit_msg>[DROOLS-605] Documentation does not describe declarative enums<commit_after><?xml version="1.0" encoding="UTF-8"?>
<section version="5.0"
         xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd http://www.w3.org/1999/xlink http://www.docbook.org/xml/5.0/xsd/xlink.xsd"
         xml:base="../" xmlns="http://docbook.org/ns/docbook"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:xs="http://www.w3.org/2001/XMLSchema"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:ns="http://docbook.org/ns/docbook">
  <title>Type Declaration</title>

  <figure>
    <title>meta_data</title>

    <mediaobject>
      <imageobject>
        <imagedata align="center"
                   fileref="images/LanguageReference/meta_data.png"
                   format="PNG"/>
      </imageobject>
    </mediaobject>
  </figure>

  <figure>
    <title>type_declaration</title>

    <mediaobject>
      <imageobject>
        <imagedata align="center"
                   fileref="images/LanguageReference/type_declaration.png"
                   format="PNG"/>
      </imageobject>
    </mediaobject>
  </figure>

  <para>Type declarations have two main goals in the rules engine: to allow
  the declaration of new types, and to allow the declaration of metadata for
  types.</para>

  <itemizedlist>
    <listitem>
      <para><emphasis role="bold">Declaring new types:</emphasis> Drools works
      out of the box with plain Java objects as facts. Sometimes, however,
      users may want to define the model directly to the rules engine, without
      worrying about creating models in a lower level language like Java. At
      other times, there is a domain model already built, but eventually the
      user wants or needs to complement this model with additional entities
      that are used mainly during the reasoning process.</para>
    </listitem>

    <listitem>
      <para><emphasis role="bold">Declaring metadata:</emphasis> facts may
      have meta information associated to them. Examples of meta information
      include any kind of data that is not represented by the fact attributes
      and is consistent among all instances of that fact type. This meta
      information may be queried at runtime by the engine and used in the
      reasoning process.</para>
    </listitem>
  </itemizedlist>

  <section>
    <title>Declaring New Types</title>

    <para>To declare a new type, all you need to do is use the keyword
    <literal>declare</literal>, followed by the list of fields, and the
    keyword <literal>end</literal>. A new fact must have a list of fields,
    otherwise the engine will look for an existing fact class in the classpath
    and raise an error if not found.</para>

    <example>
      <title>Declaring a new fact type: Address</title>

      <programlisting><emphasis role="bold">declare</emphasis> Address
   number : int
   streetName : String
   city : String
<emphasis role="bold">end</emphasis>
</programlisting>
    </example>

    <para>The previous example declares a new fact type called
    <code>Address</code>. This fact type will have three attributes:
    <code>number</code>, <code>streetName</code> and <code>city</code>. Each
    attribute has a type that can be any valid Java type, including any other
    class created by the user or even other fact types previously
    declared.</para>

    <para>For instance, we may want to declare another fact type
    <code>Person</code>:</para>

    <example>
      <title>declaring a new fact type: Person</title>

      <programlisting><emphasis role="bold">declare</emphasis> Person
    name : String
    dateOfBirth : java.util.Date
    address : Address
<emphasis role="bold">end</emphasis>
</programlisting>
    </example>

    <para>As we can see on the previous example, <code>dateOfBirth</code> is
    of type <code>java.util.Date</code>, from the Java API, while
    <code>address</code> is of the previously defined fact type
    Address.</para>

    <para>You may avoid having to write the fully qualified name of a class
    every time you write it by using the <literal>import</literal> clause, as
    previously discussed.</para>

    <example>
      <title>Avoiding the need to use fully qualified class names by using
      import</title>

      <programlisting><emphasis role="bold">import</emphasis> java.util.Date

<emphasis role="bold">declare</emphasis> Person
    name : String
    dateOfBirth : Date
    address : Address
<emphasis role="bold">end</emphasis></programlisting>
    </example>

    <para>When you declare a new fact type, Drools will, at compile time,
    generate bytecode that implements a Java class representing the fact type.
    The generated Java class will be a one-to-one Java Bean mapping of the
    type definition. So, for the previous example, the generated Java class
    would be:</para>

    <example>
      <title>generated Java class for the previous Person fact type
      declaration</title>

      <programlisting language="java">public class Person implements Serializable {
    private String name;
    private java.util.Date dateOfBirth;
    private Address address;

    // empty constructor
    public Person() {...}

    // constructor with all fields 
    public Person( String name, Date dateOfBirth, Address address ) {...}

    // if keys are defined, constructor with keys
    public Person( ...keys... ) {...}

    // getters and setters
    // equals/hashCode
    // toString
}
</programlisting>
    </example>

    <para>Since the generated class is a simple Java class, it can be used
    transparently in the rules, like any other fact.</para>

    <example>
      <title>Using the declared types in rules</title>

      <programlisting><emphasis role="bold">rule</emphasis> "Using a declared Type"
<emphasis role="bold">when</emphasis> 
    $p : Person( name == "Bob" )
<emphasis role="bold">then</emphasis>
    <emphasis>// Insert Mark, who is Bob's mate.</emphasis>
    Person mark = new Person();
    mark.setName("Mark");
    insert( mark );
<emphasis role="bold">end</emphasis>
</programlisting>
    </example>

	  <section>
		  <title>Declaring enumerative types</title>
		  <para>DRL also supports the declaration of enumerative types. Such type declarations require the additional keyword
			  <emphasis>enum</emphasis>, followed by a comma separated list of admissible values terminated by a semicolon.
		  </para>
		  <example>
<programlisting>
<emphasis role="bold">declare enum</emphasis> DaysOfWeek
   SUN,MON,TUE,WED,THU,FRI,SAT;
<emphasis role="bold">end</emphasis>
</programlisting>
		  </example>
		  <para>The compiler will generate a valid Java enum, with static methods valueOf() and values(), as well as instance methods
			  ordinal(), compareTo() and name().</para>
		  <para>Complex enums are also partially supported, declaring the internal fields similarly to a regular type declaration.
			  Notice that as of version 6.x, enum fields do <emphasis>NOT</emphasis> support other declared types or enums</para>
		  <example>
<programlisting>
<emphasis role="bold">declare enum</emphasis> DaysOfWeek
   SUN("Sunday"),MON("Monday"),TUE("Tuesday"),WED("Wednesday"),THU("Thursday"),FRI("Friday"),SAT("Saturday");

   fullName : String
<emphasis role="bold">end</emphasis>
			  </programlisting>
		  </example>
		  <para>Enumeratives can then be used in rules</para>
		  <example>
			  <title>Using declarative enumerations in rules</title>
<programlisting><emphasis role="bold">rule</emphasis> "Using a declared Enum"
<emphasis role="bold">when</emphasis>
   $p : Employee( dayOff == DaysOfWeek.MONDAY )
<emphasis role="bold">then</emphasis>
   ...
<emphasis role="bold">end</emphasis>
</programlisting>
		  </example>
	  </section>
  </section>

  <section>
    <title>Declaring Metadata</title>

    <para>Metadata may be assigned to several different constructions in
    Drools: fact types, fact attributes and rules. Drools uses the at sign
    ('@') to introduce metadata, and it always uses the form:</para>

    <programlisting>@<emphasis>metadata_key</emphasis>( <emphasis>metadata_value</emphasis> )</programlisting>

    <para>The parenthesized <emphasis>metadata_value</emphasis> is
    optional.</para>

    <para>For instance, if you want to declare a metadata attribute like
{'fraction_non_alphanumeric': 0.10958542381832585, 'fraction_numerical': 0.004753102719831001, 'mean_word_length': 3.3061398521887435, 'pattern_counts': {'":': 0, '<': 345, '<?xml version=': 2, '>': 345, 'https://': 0, 'lorem ipsum': 0, 'www.': 14, 'xml': 20}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1090463', 'n_tokens_mistral': 4437, 'n_tokens_neox': 4117, 'n_words': 1470}