1 files changed, 74 insertions, 0 deletions
diff --git a/documentation/sqlcontainer/sqlcontainer-referencing.asciidoc b/documentation/sqlcontainer/sqlcontainer-referencing.asciidoc
new file mode 100644
index 0000000000..b31b10d39d
--- /dev/null
+++ b/documentation/sqlcontainer/sqlcontainer-referencing.asciidoc
@@ -0,0 +1,74 @@
+---
+title: Referencing Another SQLContainer
+order: 6
+layout: page
+---
+
+[[sqlcontainer.referencing]]
+= Referencing Another SQLContainer
+
+When developing a database-connected application, there is usually a need to
+retrieve data related to one table from one or more other tables. In most cases,
+this relation is achieved with a foreign key reference, where a column of the
+first table contains a primary key or candidate key of a row in another table.
+
+SQLContainer offers limited support for this kind of referencing relation,
+although all referencing is currently done on the Java side so no constraints
+need to be made in the database. A new reference can be created by calling the
+following method:
+
+
+----
+public void addReference(SQLContainer refdCont,
+                         String refingCol, String refdCol);
+----
+
+This method should be called on the source container of the reference. The
+target container should be given as the first parameter. The
+[parameter]#refingCol# is the name of the 'foreign key' column in the source
+container, and the [parameter]#refdCol# is the name of the referenced key column
+in the target container.
+
+__Note: For any [classname]#SQLContainer#, all the referenced target containers
+must be different. You can not reference the same container from the same source
+twice.__
+
+Handling the referenced item can be done through the three provided set/get
+methods, and the reference can be completely removed with the
+[methodname]#removeReference()# method. Signatures of these methods are listed
+below:
+
+
+----
+public boolean setReferencedItem(Object itemId,
+        Object refdItemId, SQLContainer refdCont)
+public Object getReferencedItemId(Object itemId,
+                                  SQLContainer refdCont)
+public Item getReferencedItem(Object itemId,
+                              SQLContainer refdCont)
+public boolean removeReference(SQLContainer refdCont)
+----
+
+The setter method should be given three parameters: [parameter]#itemId# is the
+ID of the referencing item (from the source container), [parameter]#refdItemId#
+is the referenced [parameter]#itemID# (from the target container) and
+[parameter]#refdCont# is a reference to the target container that identifies the
+reference. This method returns true if the setting of the referenced item was
+successful. After setting the referenced item you must normally call
+[methodname]#commit()# on the source container to persist the changes to the
+database.
+
+The [methodname]#getReferencedItemId()# method will return the item ID of the
+referenced item. As parameters this method needs the item ID of the referencing
+item and a reference to the target container as an identifier.
+[classname]#SQLContainer# also provides a convenience method
+[methodname]#getReferencedItem()#, which directly returns the referenced item
+from the target container.
+
+Finally, the referencing can be removed from the source container by calling the
+[methodname]#removeReference()# method with the target container as parameter.
+Note that this does not actually change anything in the database; it merely
+removes the logical relation that exists only on the Java-side.
+
+
+