bootstrap.sarl

/*
 * $Id$
 *
 * SARL is an general-purpose agent programming language.
 * More details on http://www.sarl.io
 *
 * Copyright (C) 2014-2017 the original authors or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package io.sarl.core

import java.lang.ref.SoftReference
import java.util.ServiceLoader
import java.util.UUID
import io.sarl.lang.core.Agent
import io.sarl.lang.core.AgentContext

/**
 * Represents an access point to the SARL run-time environment (SRE).
 * This access point may be used for accessing the underlying SRE independently of its implementation.
 *
 * <p>Depending on the implementation of the SRE, an instance of this SRE access point could be injected.
 *
 * @author $Author: sgalland$
 * @version $FullVersion$
 * @mavengroupid $GroupId$
 * @mavenartifactid $ArtifactId$
 * @since 0.6
 */
interface SREBootstrap {

	/**
	 * Start the SRE without an agent.
	 This function prepare the default context.
	 *
	 * @return the context that is created by the bootstrap. If {@code null} there is no context created.
	 * @since 0.7
	 */
	def startWithoutAgent : AgentContext

	/**
	 * Launch the SRE and the first agent in the kernel.
	 *
	 * <p>The function {@link #getBootAgentIdentifier()} permits to retrieve the identifier of the launched agent.
	 *
	 * @param agentCls - type of the first agent to launch.
	 * @param params - parameters to pass to the agent as its initialization parameters.
	 * @return the identifier of the created agent.
	 * @throws Exception - if it is impossible to start the platform.
	 * @see #getBootAgentIdentifier()
	 */
	def startAgent(agentCls : Class<? extends Agent>, params : Object*) : UUID throws Exception

	/**
	 * Launch the SRE and the first agent in the kernel.
	 *
	 * <p>The function {@link #getBootAgentIdentifier()} permits to retrieve the identifier of the launched agent.
	 *
	 * @param nbAgents - the number of agents to be launched.
	 * @param agentCls - type of the first agent to launch.
	 * @param params - parameters to pass to the agent as its initialization parameters.
	 * @return the identifiers of the created agents.
	 * @throws Exception - if it is impossible to start the platform.
	 * @see #getBootAgentIdentifier()
	 */
	def startAgent(nbAgents : int, agentCls : Class<? extends Agent>, params : Object*) : Iterable<UUID> throws Exception

	/**
	 * Replies the identifier of the boot agent from the system's properties. The boot agent is launched with
	 * {@link #startAgent(int, Class, Object...)}.
	 *
	 * @return the identifier of the boot agent, or <code>null</code> if it is unknown.
	 * @see #startAgent(int, Class, Object...)
	 */
	def getBootAgentIdentifier : UUID

	/** Replies if the bootstrap could be used.
	 *
	 * <p>If the bootstrap cannot be used, it cannot launch agent.
	 *
	 * @return {@code true} if the bootstrap could be used. {@code false} if it cannot be used.
	 */
	def isActive : boolean { true }
}

/**
 * Represents an access point to the SARL run-time environment (SRE).
 * This access point may be used for accessing the underlying SRE independently of its implementation.
 *
 * <p>Depending on the implementation of the SRE, an instance of this SRE access point could be injected.
 *
 * <p>For declaring a SRE bootstrap, the library that contains the contributing SRE must declared
 * a specific service implementation of {@link SREBootstrap}. The declaration of this service must be
 * done by creating a file into the folder {@code META-INF/services/io.sarl.lang.core.SREBootstrap}.
 * This file contains a single line that is the fully qualified name of the {@link SREBootstrap}'s implementation.
 *
 * @author $Author: sgalland$
 * @version $FullVersion$
 * @mavengroupid $GroupId$
 * @mavenartifactid $ArtifactId$
 * @since 0.6
 * @see ServiceLoader
 */
final class SRE {

	static var currentSRE : SREBootstrap

	static var loader : SoftReference<ServiceLoader<SREBootstrap>>

	private new {
	}

	/** Reset the service loader for the SRE bootstrap.
	 */
	static def resetServiceLoader() : void {
		synchronized (typeof(SRE)) {
			loader = null
		}
	}

	/** Replies all the installed SRE into the classpath.
	 *
	 * @param onlyInstalledInJRE indicates if the services will be considered only into the libraries that are
	 *    installed into the JRE. If {@code true}, only the libraries into the JRE will be considered and
	 *    the application libraries will be ignored. If {@code false}, the application libraries will be
	 *    considered as well. 
	 * @return the installed SRE.
	 */
	static def getServiceLoader(onlyInstalledInJRE : boolean = false) : ServiceLoader<SREBootstrap> {
		synchronized (typeof(SRE)) {
			var sl = if (loader === null) null else loader.get
			if (sl === null) {
			    if (onlyInstalledInJRE) {
					sl = ServiceLoader::loadInstalled(typeof(SREBootstrap))
				} else {
					sl = ServiceLoader::load(typeof(SREBootstrap))
				}
				loader = new SoftReference(sl)
			}
			return sl
		}
	}

	/** Change the current SRE.
	 *
	 * @param sre the current SRE.
	 */
	static def setBootstrap(sre : SREBootstrap) {
		synchronized (typeof(SRE)) {
			currentSRE = sre
		}
	}

	/** Find and reply the current SRE.
	 *
	 * @return the current SRE, never {@code null}.
	 * @throws IllegalStateException if a SRE cannot be found.
	 */
	static def getBootstrap : SREBootstrap {
		synchronized (typeof(SRE)) {
			if (currentSRE === null) {
				val iterator = getServiceLoader.iterator
				if (iterator.hasNext) {
					currentSRE = iterator.next
				} else {
					currentSRE = new VoidSREBootstrap
				}
			}
			return currentSRE
		}
	}

	/**
	 * Private API: not documented.
	 *
	 * @author $Author: sgalland$
	 * @version $FullVersion$
	 * @mavengroupid $GroupId$
	 * @mavenartifactid $ArtifactId$
	 * @since 0.6
	 */
	private static class VoidSREBootstrap implements SREBootstrap {

		package new {
		}

		override startWithoutAgent : AgentContext {
			null
		}

		override startAgent(agentCls : Class<? extends Agent>, params : Object*) : UUID {
			throw new UnsupportedOperationException
		}

		override startAgent(nbAgents : int, agentCls : Class<? extends Agent>, params : Object*) : Iterable<UUID> {
			throw new UnsupportedOperationException
		}

		override getBootAgentIdentifier : UUID {
			throw new UnsupportedOperationException
		}

		override isActive : boolean {
			false
		}

	}

}