Author: dspicar
Date: Mon Jan 23 14:10:36 2012
New Revision: 1234804
URL: http://svn.apache.org/viewvc?rev=1234804&view=rev
Log:
CLEREZZA-617: added better code documentation
Modified:
incubator/clerezza/issues/CLEREZZA-617/platform.typerendering.scalaserverpages/src/main/java/org/apache/clerezza/platform/typerendering/scalaserverpages/ScalaServerPagesService.java
incubator/clerezza/issues/CLEREZZA-617/scala-scripting/script-engine/src/main/scala/org/apache/clerezza/scala/scripting/CompilerService.scala
incubator/clerezza/issues/CLEREZZA-617/scala-scripting/script-engine/src/main/scala/org/apache/clerezza/scala/scripting/TrackingCompiler.scala
Modified:
incubator/clerezza/issues/CLEREZZA-617/platform.typerendering.scalaserverpages/src/main/java/org/apache/clerezza/platform/typerendering/scalaserverpages/ScalaServerPagesService.java
URL:
http://svn.apache.org/viewvc/incubator/clerezza/issues/CLEREZZA-617/platform.typerendering.scalaserverpages/src/main/java/org/apache/clerezza/platform/typerendering/scalaserverpages/ScalaServerPagesService.java?rev=1234804&r1=1234803&r2=1234804&view=diff
==============================================================================
---
incubator/clerezza/issues/CLEREZZA-617/platform.typerendering.scalaserverpages/src/main/java/org/apache/clerezza/platform/typerendering/scalaserverpages/ScalaServerPagesService.java
(original)
+++
incubator/clerezza/issues/CLEREZZA-617/platform.typerendering.scalaserverpages/src/main/java/org/apache/clerezza/platform/typerendering/scalaserverpages/ScalaServerPagesService.java
Mon Jan 23 14:10:36 2012
@@ -30,6 +30,7 @@ import org.osgi.service.component.Compon
import javax.ws.rs.core.MediaType;
import java.net.URL;
+import org.apache.clerezza.platform.typerendering.WebRenderingService;
/**
*
@@ -58,13 +59,20 @@ public class ScalaServerPagesService {
/**
* Creates a Renderlet-Service registered using the BundleContext of
this
- * service
+ * service.
*
- * @param location
- * @param rdfType
- * @param modePattern
- * @param mediaType
- * @return
+ * @param location
+ * The location of the SSP source file.
+ * @param rdfType
+ * The RDF-type to use this Renderlet for.
+ * @param modePattern
+ * an optional mode string used to distinguish different
Renderlets
+ * bound to the same RDF-type. Can be null.
+ * @param mediaType
+ * The media type produced by this Renderlet (e.g.
application/xhtml+xml).
+ * @return
+ * The registered Renderlet-Service. Can be used to
update/unregister
+ * the Renderlet-Service.
*/
public ServiceRegistration registerScalaServerPage(URL location, UriRef
rdfType,
String modePattern, MediaType mediaType) {
@@ -72,16 +80,24 @@ public class ScalaServerPagesService {
}
/**
- * Creates a renderlet service registered using the given bundle
context. Using
- * This method ensures that the passed BundleContext is used to
determine the priority
- * of the renderlets.
+ * Creates a Renderlet-Service registered using the given
BundleContext.
+ * Using this method ensures that the passed BundleContext is used to
+ * determine the priority of the Renderlets and OSGi service
dependencies.
*
- * @param location
- * @param rdfType
- * @param modePattern
- * @param mediaType
+ * @param location
+ * The location of the SSP source file.
+ * @param rdfType
+ * The RDF-type to use this Renderlet for.
+ * @param modePattern
+ * an optional mode string used to distinguish different
Renderlets
+ * bound to the same RDF-type. Can be null.
+ * @param mediaType
+ * The media type produced by this Renderlet (e.g.
application/xhtml+xml).
* @param callerBundleContext
- * @return
+ * The BundleContext used to register the
Renderlet-Service with.
+ * @return
+ * The registered Renderlet-Service. Can be used to
update/unregister
+ * the Renderlet-Service.
*/
public ServiceRegistration registerScalaServerPage(URL location,
UriRef rdfType,
String modePattern, MediaType mediaType, BundleContext
callerBundleContext) {
@@ -90,11 +106,54 @@ public class ScalaServerPagesService {
}
/**
- * Creates a renderlet service registered using the given bundle
context. Using
- * This method ensures that the passed BundleContext is used to
determine the priority
- * of the renderlets.
+ * Creates a Renderlet-Service registered using the given
BundleContext.
+ * Ensures that the passed BundleContext is used to determine the
priority
+ * of the Renderlets and OSGi service dependencies.
*
- * The passed class loader will be used to load the compiled SSP.
+ * Using this method ensures that the provided class loader loads the
compiled
+ * Scala Server Page (SSP).
+ *
+ * It is recommended to use this method when registering a SSP that
+ * references a WebrenderingService. The class loader should be the
+ * bundle class loader of the bundle registering the SSP. See NOTES
below
+ * for more detail.
+ *
+ * NOTES:
+ * - In an OSGi environment you probably want to supply a bundle class
+ * loader.
+ * - Be aware of the implications on OSGi package dependencies.
+ * All packages referenced in the SSP source file will become
dependencies
+ * of the bundle whose class loader is used.
+ * - It is the responsibility of the client of this service to
+ * declare the additional runtime package dependencies or dynamic
imports in
+ * the appropriate Bundle's manifest header.
+ * - Minimal package requirements at runtime are (required by all SSPs):
+ * scala,
+ * scala.reflect,
+ * scala.collection,
+ * scala.xml,
+ * org.apache.clerezza.platform.typerendering.scala
+ *
+ * @see http://wiki.osgi.org/wiki/Import-Package
+ * @see http://wiki.osgi.org/wiki/DynamicImport-Package
+ * @see WebRenderingService
+ *
+ * @param location
+ * The location of the SSP source file.
+ * @param rdfType
+ * The RDF-type to use this Renderlet for.
+ * @param modePattern
+ * an optional mode string used to distinguish different
Renderlets
+ * bound to the same RDF-type. Can be null.
+ * @param mediaType
+ * The media type produced by this Renderlet (e.g.
application/xhtml+xml).
+ * @param callerBundleContext
+ * The BundleContext used to register the
Renderlet-Service with.
+ * @param classLoader
+ * The class loader to load compiled SSP with.
+ * @return
+ * The registered Renderlet-Service. Can be used to
update/unregister
+ * the Renderlet-Service.
*/
public ServiceRegistration registerScalaServerPage(URL location,
UriRef rdfType,
String modePattern, MediaType mediaType, BundleContext
callerBundleContext,
Modified:
incubator/clerezza/issues/CLEREZZA-617/scala-scripting/script-engine/src/main/scala/org/apache/clerezza/scala/scripting/CompilerService.scala
URL:
http://svn.apache.org/viewvc/incubator/clerezza/issues/CLEREZZA-617/scala-scripting/script-engine/src/main/scala/org/apache/clerezza/scala/scripting/CompilerService.scala?rev=1234804&r1=1234803&r2=1234804&view=diff
==============================================================================
---
incubator/clerezza/issues/CLEREZZA-617/scala-scripting/script-engine/src/main/scala/org/apache/clerezza/scala/scripting/CompilerService.scala
(original)
+++
incubator/clerezza/issues/CLEREZZA-617/scala-scripting/script-engine/src/main/scala/org/apache/clerezza/scala/scripting/CompilerService.scala
Mon Jan 23 14:10:36 2012
@@ -49,6 +49,9 @@ class CompilePermission extends Permissi
override def hashCode = classOf[CompilePermission].hashCode
}
+/**
+ * An OSGi service providing dynamic runtime scala compilation from source
files.
+ */
class CompilerService() extends BundleListener {
protected var bundleContext : BundleContext = null;
@@ -96,18 +99,44 @@ class CompilerService() extends BundleLi
}
/**
- * Compiles an array of class sources returning an array of compiled
classes.
- * Uses the optionally supplied class loader to load compiled classes.
- * If no class loader is supplied, the class loader of this bundle is
used.
+ * Compiles an array of class sources returning an array of compiled
and
+ * loaded classes.
+ *
+ * NOTE: The classes are loaded using the bundle class loader of
+ * this service. Be aware of the implications on OSGi package
dependencies.
+ * All packages referenced in the sources will become dependencies of
the
+ * compiler service and not of bundle using this service.
*/
def compile(sources: Array[Array[Char]]): Array[Class[_]] = {
compile(sources, null)
}
/**
- * Compiles an array of class sources returning an array of compiled
classes.
- * Uses the optionally supplied class loader to load compiled classes.
- * If no class loader is supplied, the class loader of this bundle is
used.
+ * Compiles an array of class sources returning an array of compiled
and
+ * loaded classes.
+ *
+ * The supplied class loader is used to load compiled classes. It must
have
+ * a view of all classes referenced in the source files.
+ *
+ * NOTES:
+ * - In an OSGi environment you probably want to supply a bundle class
+ * loader.
+ * - Be aware of the implications on OSGi package dependencies.
+ * All packages referenced in the sources will become dependencies of
the
+ * bundle whose class loader is used.
+ * - It is the responsibility of the client of this service to
+ * declare the additional runtime package dependencies or dynamic
imports in
+ * the appropriate bundle's manifest header.
+ * - Minimal package requirements at runtime are (required by all SSPs):
+ * scala,
+ * scala.reflect,
+ * scala.collection,
+ * scala.xml,
+ * org.apache.clerezza.platform.typerendering.scala
+ *
+ * @see http://wiki.osgi.org/wiki/Import-Package
+ * @see http://wiki.osgi.org/wiki/DynamicImport-Package
+ *
*/
def compile(sources: Array[Array[Char]], classLoader: ClassLoader):
Array[Class[_]] = {
var classLoaderOption: Option[ClassLoader] = None
@@ -118,9 +147,32 @@ class CompilerService() extends BundleLi
}
/**
- * Compiles a list of class sources returning a list of compiled
classes.
- * Uses the optionally supplied class loader to load compiled classes.
- * If no class loader is supplied, the class loader of this bundle is
used.
+ * Compiles an array of class sources returning an array of compiled
and
+ * loaded classes.
+ *
+ * If some class loader is supplied it is used to load compiled
classes.
+ * It must have a view of all classes referenced in the source files.
+ * If no class loader is supplied the classes are loaded using the
bundle
+ * class loader of this service.
+ *
+ * NOTES (if a custom class loader is supplied):
+ * - In an OSGi environment you probably want to supply a bundle class
+ * loader.
+ * - Be aware of the implications on OSGi package dependencies.
+ * All packages referenced in the sources will become dependencies of
the
+ * bundle whose class loader is used.
+ * - It is the responsibility of the client of this service to
+ * declare the additional runtime package dependencies or dynamic
imports in
+ * the appropriate bundle's manifest header.
+ * - Minimal package requirements at runtime are (required by all SSPs):
+ * scala,
+ * scala.reflect,
+ * scala.collection,
+ * scala.xml,
+ * org.apache.clerezza.platform.typerendering.scala
+ *
+ * @see http://wiki.osgi.org/wiki/Import-Package
+ * @see http://wiki.osgi.org/wiki/DynamicImport-Package
*/
def compile(sources: List[Array[Char]], classLoaderOption:
Option[ClassLoader] = None): List[Class[_]] = {
AccessController.checkPermission(new CompilePermission)
Modified:
incubator/clerezza/issues/CLEREZZA-617/scala-scripting/script-engine/src/main/scala/org/apache/clerezza/scala/scripting/TrackingCompiler.scala
URL:
http://svn.apache.org/viewvc/incubator/clerezza/issues/CLEREZZA-617/scala-scripting/script-engine/src/main/scala/org/apache/clerezza/scala/scripting/TrackingCompiler.scala?rev=1234804&r1=1234803&r2=1234804&view=diff
==============================================================================
---
incubator/clerezza/issues/CLEREZZA-617/scala-scripting/script-engine/src/main/scala/org/apache/clerezza/scala/scripting/TrackingCompiler.scala
(original)
+++
incubator/clerezza/issues/CLEREZZA-617/scala-scripting/script-engine/src/main/scala/org/apache/clerezza/scala/scripting/TrackingCompiler.scala
Mon Jan 23 14:10:36 2012
@@ -65,9 +65,14 @@ class TrackingCompiler private (bundleCo
}
/**
- * Compiles a list of class sources returning a list of compiled
classes.
- * Uses the optionally supplied class loader to load compiled classes.
- * If no class loader is supplied, the class loader of this class is
used.
+ * Compiles a list of class sources returning a list of compiled and
loaded
+ * classes.
+ *
+ * Optionally a class loader can be supplied.
+ * If some class loader is supplied the source classes are loaded with
a
+ * custom class loader that uses the supplied class loader as parent.
+ * If no class loader is supplied, the class loader of this class is
used
+ * as parent.
*/
@throws(classOf[CompileErrorsException])
def compile(sources: List[Array[Char]], classLoaderOption:
Option[ClassLoader] = None): List[Class[_]] = {
