From f086143e8281fdda7876fa9f9707fe7287b428c9 Mon Sep 17 00:00:00 2001
From: Robert von Burg <eitch@eitchnet.ch>
Date: Fri, 17 Feb 2017 17:37:41 +0100
Subject: [PATCH] [Minor] JavaDoc updates for StrolchRealm

---
 .../li/strolch/agent/api/StrolchRealm.java    | 102 +++++++++++++++++-
 .../agent/impl/InternalStrolchRealm.java      |   2 +-
 2 files changed, 102 insertions(+), 2 deletions(-)

diff --git a/li.strolch.agent/src/main/java/li/strolch/agent/api/StrolchRealm.java b/li.strolch.agent/src/main/java/li/strolch/agent/api/StrolchRealm.java
index 5f92bf20c..4282c751c 100644
--- a/li.strolch.agent/src/main/java/li/strolch/agent/api/StrolchRealm.java
+++ b/li.strolch.agent/src/main/java/li/strolch/agent/api/StrolchRealm.java
@@ -21,31 +21,131 @@ import li.strolch.persistence.api.StrolchTransaction;
 import li.strolch.privilege.model.Certificate;
 
 /**
+ * <p>
+ * A {@link StrolchRealm} implement mandate separation. Each realm has its own {@link ElementMap ElementMaps} and can be
+ * configured separately to other realms. So cached realms and transient realms can reside in the same agent.
+ * </p>
+ * 
+ * <p>
+ * A realm can support the following functionality:
+ * </p>
+ * <ul>
+ * <li>opening of transactions (mandator)</li>
+ * <li>locking of objects (mandatory)</li>
+ * <li>different modes see {@link DataStoreMode}</li>
+ * <li>audit trail for write</li>
+ * <li>audit trail for read</li>
+ * <li>observer updates</li>
+ * <li>element versioning</li>
+ * </ul>
+ * 
  * @author Robert von Burg <eitch@eitchnet.ch>
  */
 public interface StrolchRealm {
 
+	/**
+	 * Returns the name of the realm
+	 * 
+	 * @return the name of the realm
+	 */
 	public String getRealm();
 
+	/**
+	 * Locks the given element
+	 * 
+	 * @param element
+	 *            the element to lock
+	 * 
+	 * @see LockHandler#lock(StrolchRootElement)
+	 */
 	public void lock(StrolchRootElement element);
 
+	/**
+	 * Unlocks the given element (lock might still be held, if lock counter is used)
+	 * 
+	 * @param lockedElement
+	 *            the element to unlock
+	 * 
+	 * @see LockHandler#unlock(StrolchRootElement)
+	 */
 	public void unlock(StrolchRootElement lockedElement);
 
+	/**
+	 * Releases the lock for the given element
+	 * 
+	 * @param lockedElement
+	 *            the element for which to release the lock
+	 * 
+	 * @see LockHandler#releaseLock(StrolchRootElement)
+	 */
 	public void releaseLock(StrolchRootElement lockedElement);
 
+	/**
+	 * Returns the {@link DataStoreMode}
+	 * 
+	 * @return the {@link DataStoreMode}
+	 */
 	public DataStoreMode getMode();
 
+	/**
+	 * Opens a {@link StrolchTransaction} for the given certificate
+	 * 
+	 * @param certificate
+	 *            the authenticated certificate
+	 * @param clazz
+	 *            to give the transaction an action name
+	 * 
+	 * @return the newly created transaction
+	 */
 	public StrolchTransaction openTx(Certificate certificate, Class<?> clazz);
 
+	/**
+	 * Opens a {@link StrolchTransaction} for the given certificate
+	 * 
+	 * @param certificate
+	 *            the authenticated certificate
+	 * @param action
+	 *            to give the transaction an action name
+	 * 
+	 * @return the newly created transaction
+	 */
 	public StrolchTransaction openTx(Certificate certificate, String action);
 
+	/**
+	 * Returns if the audit trail is enabled for reads
+	 * 
+	 * @return if the audit trail is enabled for reads
+	 */
 	public boolean isAuditTrailEnabledForRead();
 
+	/**
+	 * Returns if the audit trail is enabled for modifications
+	 * 
+	 * @return if the audit trail is enabled for modifications
+	 */
 	public boolean isAuditTrailEnabled();
 
+	/**
+	 * Returns if observer updates is enabled
+	 * 
+	 * @return if observer updates is enabled
+	 */
 	public boolean isUpdateObservers();
 
+	/**
+	 * Returns if versioning is enabled
+	 * 
+	 * @return if versioning is enabled
+	 */
 	public boolean isVersioningEnabled();
 
-	public ObserverHandler getObserverHandler();
+	/**
+	 * Returns the {@link ObserverHandler} if observer updates are enabled
+	 * 
+	 * @return the {@link ObserverHandler} if observer updates are enabled
+	 * 
+	 * @throws IllegalArgumentException
+	 *             if observer updates are not enabled
+	 */
+	public ObserverHandler getObserverHandler() throws IllegalArgumentException;
 }
diff --git a/li.strolch.agent/src/main/java/li/strolch/agent/impl/InternalStrolchRealm.java b/li.strolch.agent/src/main/java/li/strolch/agent/impl/InternalStrolchRealm.java
index 7c2f7a326..7e613ccb2 100644
--- a/li.strolch.agent/src/main/java/li/strolch/agent/impl/InternalStrolchRealm.java
+++ b/li.strolch.agent/src/main/java/li/strolch/agent/impl/InternalStrolchRealm.java
@@ -152,7 +152,7 @@ public abstract class InternalStrolchRealm implements StrolchRealm {
 	}
 
 	@Override
-	public ObserverHandler getObserverHandler() {
+	public ObserverHandler getObserverHandler() throws IllegalArgumentException{
 		if (!this.updateObservers)
 			throw new IllegalArgumentException("ObserverUpdates are not enabled!"); //$NON-NLS-1$
 		return this.observerHandler;