..	*******************************************************************************
	* MetaFactory.io R2
	* Technical Documentation
	* 
	* File name   : ModRef_Reference.rst
	* Created by  : Marnix Bochove (original text)
	* Last update : 24-03-2021
	* Updated by  : Niels de Nies
	*
	* MetaFactory BV Amsterdam 
	*******************************************************************************

.. include:: /inline-images.txt

Reference
=========

<reference> is a sub element of :ref:`object <Reference/ModelReference/ModRef_Object:Object>`
and defines a relation with another object in the same package.
Inside this object scope the name of the reference has to be unique.
An object can contain any number of references.

.. code-block:: xml
	:caption: <reference/> example
	:name: MR-reference-01
	:linenos:
	:emphasize-lines: 8

	<model>
		...
		
		<package name="yourModelPackage">
		
			<object name="yourObjectName01">
				...
				<reference name="yourReferenceName" type="nameOfReferencedObject" multiplicity="0..n" notnull="true"></reference>
				...
			</object>
		</package>
		
		...
	</model>

.. rubric:: Syntax

.. code-block:: xml

	<reference name=”” type=”” length=”” multiplicity=”” notnull=””> </reference>

.. rubric:: Attributes

..	list-table:: **attributes of <reference/>**
	:widths: 15 70 15
	:header-rows: 1
	:class: tight-table

	*	-	Name
		-	Details
		-	Required
	*	-	name
		-	Name of the reference – has to be unique within the context of the object it is defined in.
		-	mandatory
	*	-	type
		-	Data type of this reference (integer, boolean, string, other object…)
		-	mandatory
	*	-	multiplicity
		-	Sets the multiplicity of the relation between the object of the reference and the object referred to.
			
			multiplicity=”0..1| 1..1| 0..n| 1..n| n..n”
		-	mandatory
	*	-	notnull
		-	This flag attribute tells whether its reference is allowed to be undefined (notnull=’FALSE”) or not (notnull=”TRUE”).
			
			notnull=”false|true” with default “false”
		-	optional


Exxample from the Bookstore application: an Author has a reference to Book, and the Book has references to Author and Category.

.. code-block:: xml
	:caption: <reference/> example
	:name: MR-reference-02
	:linenos:
	:emphasize-lines: 10, 18-20, 25
	
	<model>
		
		<package name="domain">

			<!--Assume we have authors who write books-->
			<object name="Author">
				<attribute name="firstName" type="String" length="50" notnull="true" />
				<attribute name="lastName" type="String" length="100" notnull="true" />

				<reference name="book" type="Book" multiplicity="0..n"></reference>
			</object>

			<!--A book that is written by one author and the book belongs to a category-->
			<object name="Book">
				<attribute name="name" type="String" length="100" notnull="true" />
				<attribute name="description" type="String" length="255" notnull="true" />

				<reference name="author" type="Author" multiplicity="1..1"></reference>
				<reference name="category" type="Category" multiplicity="0..1" notnull="false">
				</reference>
			</object>

			<object name="Category">
				<attribute name="name" type="String" notnull="true" length="20" />
				<attribute name="description" type="String" notnull="false" length="200" />
				<reference name="book" type="Book" multiplicity="0..n"></reference>
			</object>
		</package>
	</model>

.. rubric:: Sub elements

..	list-table:: <package/> sub elements
	:widths: 15 70 15
	:header-rows: 1
	:class: tight-table

	*	-	Name
		-	Details
		-	Number
	*	-	:ref:`metadata <Reference/ModelReference/ModRef_Metadata:Metadata>`
		-	This element can contain properties that are specific to the package.
		-	0..n