[New] Added ExecutionPolicy.runAsAgentWithResult()

li.strolch.service/src/main/java/li/strolch/execution/policy/ExecutionPolicy.java

@@ -15,6 +15,7 @@ import li.strolch.privilege.model.Certificate;
 import li.strolch.privilege.model.PrivilegeContext;
 import li.strolch.runtime.StrolchConstants;
 import li.strolch.runtime.privilege.PrivilegedRunnable;
+import li.strolch.runtime.privilege.PrivilegedRunnableWithResult;
 
 /**
  * <p>
@@ -22,12 +23,12 @@ import li.strolch.runtime.privilege.PrivilegedRunnable;
  * performed by calling {@link #toExecution(Action)} and the execution policy then implements some logic to change the
  * state to {@link State#EXECUTION}. Here often communication with an external system is performed.
  * </p>
- * 
+ *
  * <p>
  * Note that the public methods on this interface are always called from a instance of the concrete class, thus any
  * instance fields are not kept from previous invocations
  * </p>
- * 
+ *
  * @author Robert von Burg <eitch@eitchnet.ch>
  */
 public abstract class ExecutionPolicy extends StrolchPolicy {
@@ -59,17 +60,17 @@ public abstract class ExecutionPolicy extends StrolchPolicy {
 	 * Evaluates if the given {@link Action} is executable i.e. any state has the expected values so that the given
 	 * {@link Action} can have its execution be started.
 	 * </p>
-	 * 
+	 *
 	 * <p>
 	 * <b>Note:</b> The default implementation is to always allow execution. Subclasses can override this method and
 	 * define a required state which is to be met for execution of the given {@link Action}.
 	 * </p>
-	 * 
+	 *
 	 * @param action
-	 *            the {@link Action} to check if it can be executed
+	 * 		the {@link Action} to check if it can be executed
-	 * 
+	 *
 	 * @return true if the action can be executed, false if not, i.e. the current state disallows the action to be
-	 *         executed
+	 * executed
 	 */
 	public boolean isExecutable(Action action) {
 		return true;
@@ -77,44 +78,44 @@ public abstract class ExecutionPolicy extends StrolchPolicy {
 
 	/**
 	 * Starts the execution of the given {@link Action}, i.e. sets the state to {@link State#EXECUTION}
-	 * 
+	 *
 	 * @param action
-	 *            the action to start execution for
+	 * 		the action to start execution for
 	 */
 	public abstract void toExecution(Action action);
 
 	/**
 	 * Completes execution of the given {@link Action}, i.e. sets the state to {@link State#EXECUTED}
-	 * 
+	 *
 	 * @param action
-	 *            the action to set to executed
+	 * 		the action to set to executed
 	 */
 	public abstract void toExecuted(Action action);
 
 	/**
-	 * Stops the execution of this {@link Action} without completing its execution, i.e. sets the state to
+	 * Stops the execution of this {@link Action} without completing its execution, i.e. sets the state to {@link
-	 * {@link State#STOPPED}
+	 * State#STOPPED}
-	 * 
+	 *
 	 * @param action
-	 *            the action to stop execution for
+	 * 		the action to stop execution for
 	 */
 	public abstract void toStopped(Action action);
 
 	/**
-	 * Sets this {@link Action} which should be in execution to an error state, i.e. sets the state to
+	 * Sets this {@link Action} which should be in execution to an error state, i.e. sets the state to {@link
-	 * {@link State#ERROR}
+	 * State#ERROR}
-	 * 
+	 *
 	 * @param action
-	 *            the action to set to error state
+	 * 		the action to set to error state
 	 */
 	public abstract void toError(Action action);
 
 	/**
-	 * Sets this {@link Action} which should be in execution to a warning state, i.e. sets the state to
+	 * Sets this {@link Action} which should be in execution to a warning state, i.e. sets the state to {@link
-	 * {@link State#WARNING}
+	 * State#WARNING}
-	 * 
+	 *
 	 * @param action
-	 *            the action to set to warning state
+	 * 		the action to set to warning state
 	 */
 	public abstract void toWarning(Action action);
 
@@ -135,7 +136,7 @@ public abstract class ExecutionPolicy extends StrolchPolicy {
 
 	/**
 	 * @return the {@link DelayedExecutionTimer} to simplify the delayed execution of an {@link Action}, e.g. for
-	 *         simulated execution or simple wait tasks
+	 * simulated execution or simple wait tasks
 	 */
 	protected DelayedExecutionTimer getDelayedExecutionTimer() {
 		return getComponent(ExecutionHandler.class).getDelayedExecutionTimer();
@@ -143,7 +144,7 @@ public abstract class ExecutionPolicy extends StrolchPolicy {
 
 	/**
 	 * Returns the execution handler instance
-	 * 
+	 *
 	 * @return the {@link ExecutionHandler} instance
 	 */
 	protected ExecutionHandler getExecutionHandler() {
@@ -151,14 +152,13 @@ public abstract class ExecutionPolicy extends StrolchPolicy {
 	}
 
 	/**
-	 * Opens a {@link StrolchTransaction} where the realm retrieved using
+	 * Opens a {@link StrolchTransaction} where the realm retrieved using {@link ComponentContainer#getRealm(Certificate)}.
-	 * {@link ComponentContainer#getRealm(Certificate)}. This transaction should be used in a try-with-resource clause
+	 * This transaction should be used in a try-with-resource clause so it is properly closed.
-	 * so it is properly closed.
+	 *
-	 * 
 	 * @return the open {@link StrolchTransaction}
-	 * 
+	 *
 	 * @throws StrolchException
-	 *             if the {@link StrolchRealm} does not exist with the given name
+	 * 		if the {@link StrolchRealm} does not exist with the given name
 	 */
 	protected StrolchTransaction openTx(PrivilegeContext ctx) throws StrolchException {
 		if (this.tx.isOpen())
@@ -170,13 +170,30 @@ public abstract class ExecutionPolicy extends StrolchPolicy {
 
 	/**
 	 * Performs the given {@link PrivilegedRunnable} as the system user {@link StrolchConstants#SYSTEM_USER_AGENT}
-	 * 
+	 *
 	 * @param runnable
-	 *            the runnable to perform
+	 * 		the runnable to perform
-	 * 
+	 *
-	 * @throws PrivilegeException if the agent is missing the privilege
+	 * @throws PrivilegeException
+	 * 		if the agent is missing the privilege
 	 */
 	protected void runAsAgent(PrivilegedRunnable runnable) throws PrivilegeException {
 		getContainer().getPrivilegeHandler().runAs(StrolchConstants.SYSTEM_USER_AGENT, runnable);
 	}
+
+	/**
+	 * Performs the given {@link PrivilegedRunnableWithResult} as the system user {@link
+	 * StrolchConstants#SYSTEM_USER_AGENT}
+	 *
+	 * @param runnable
+	 * 		the runnable to perform
+	 *
+	 * @return the result of the operation
+	 *
+	 * @throws PrivilegeException
+	 * 		if the agent is missing the privilege
+	 */
+	protected <T> T runAsAgentWithResult(PrivilegedRunnableWithResult<T> runnable) throws PrivilegeException {
+		return getContainer().getPrivilegeHandler().runWithResult(StrolchConstants.SYSTEM_USER_AGENT, runnable);
+	}
 }