API

application

Though the "application" service of the configuration scripts is different from that of your Prudence application, you can access the Prudence "application" service in that application's "default.*" script as "applicationService". For example, you can access the application logger as "applicationService.logger".

Though application.globals is thread safe, it's important to understand how to use it properly. Make sure you read the section on concurrency in "sharing state".

var dbConnection = application.globals.get('db.connection')
if((dbConnection === null) && (application.sharedGlobals !== null)) {
	// Was not in application globals, so try shared globals
	dbConnection = application.sharedGlobals.get('db.connection')
}

1. The application's full name, per the application setting, or null to run in this application.
2. The document name in /tasks/.
3. The entry point name (or null). If not specified, then the document in /tasks/ will be simply executed. If specified, then the document will be executed only once, and subsequent calls will involve calling the entry point names here. This may result in better performance for tasks that are called very often. See handlers for more information on how entry points work. Note that entry points are specified in camel case, and are converted to format appropriate for your flavor of Prudence. For example, an entry point named "handleTask" will be called as "handle_task" in Python and "handle-task" in Clojure.
4. The context (or null). This is later available for the task as document.context.
5. Initial delay in milliseconds, or zero for ASAP.
6. Repeat delay in milliseconds, or zero for no repetition.
7. Whether repetitions are at fixed times (true), or if the repeat delay begins when the task ends (false). This value matters only if the repeat delay is greater than zero. Note that "true" may cause a new instance of the task to be spawned again before the previous one completes.

application.task(null, '/email/reminders/', null, null, 0, 10 * 60 * 1000, true)

application.task(null, '/database/cleanup/', null, 'fast', 0, 0, false).get()

var cleanup = application.globals.get('myapp.task.cleanup')
if(cleanup && cleanup.done) {
	application.logger.info('Database already clean!')
} else {
	application.globals.put('myapp.task.cleanup', application.task(null, '/database/cleanup/', null, null, 0, 0, false))
}

1. The application's full name, per the application setting, or null to run in this application.
2. The document name in /tasks/.
3. The entry point name (or null).
4. The context (or null). Note that for distributed tasks, unlike in-process tasks, the context must be serializable. Depending on your object implementation, this may mean having to manually serialize/deserialize the context into a string or another serializable format.
5. Where to run the task:
   1. Null: let Hazelcast decide
   2. Member instance: the particular cluster member
   3. String: the particular cluster member for this key
   4. Iterable of Member instances: run on one or all of these members (see the sixth argument, below)
6. Multi-task support: whether the task should run on each member of the cluster (true), or on just one (false). Only applicable if "where" is an iterable of member instances.

document

This Document

Note: Passing the "document" global variable as an argument to a function in another document will not let that other document access attributes for the calling document. In fact, all documents in the current thread share the same "document" service, which internally gets and sets attributes for the document in which it is accessed. If you do have a need for a function in one document to manipulate the "document" attributes of another document, you will have to return the values and have code in the owning document explicitly set the attributes there.

Note that if you edit the source file such as that it would be reloaded, within the limits defined by the minimumTimeBetweenValidityChecks setting, then any cache entries would not be used for the next request. This feature lets you see your changes on the fly, even if the document has been cached. Note, too, that updates to documents executed by your source file will also trigger this feature. See document.execute.

Rule of thumb: Set document.cacheKeyPattern to be as short as you possibly can, but not too short that it won't differentiate between different views. See the section on caching in HTML generation and "Scaling Tips" for more information on how caching can help you scale.

Important! Using document.include, or the <%& .. %> inclusion scriptlet, will cause the cache tags of the included document to be applied to the current document, and to documents that have included the current document, and so on. This is a useful feature: if a fragment included somewhere down the line is invalidated, you likely want the containing document to also be invalidated. If you wish to disable cache tag propagation, prefix the cache tag with an underscore when adding it to document.cacheTags. The tag is not stored with the underscore, and so should be referenced without the underscore when calling document.cache.invalidate.

// Implement defaults
document.execute('/defaults/instance/component/')
​
// Create an H2-database-backed cache chained after the default caches
importClass(
	com.threecrickets.prudence.cache.InProcessMemoryCache
	com.threecrickets.prudence.cache.H2Cache)
​
var chainCache = component.context.attributes.get('com.threecrickets.prudence.cache')
​
// The constructor accepts a max size in bytes (defaults to 1 MB)
// (Note that you have to make sure that the JVM has been started with a heap
// size large enough for your cache)
chainCache.caches.add(0, new InProcessMemoryCache(10 * 1024 * 1024 * 1024)) // 10 MB
​
// H2 will store its database files in the supplied path
chainCache.caches.add(new H2Cache('cache/prudence/prudence'))

importClass(
	com.threecrickets.prudence.cache.MemcachedCache,
	com.threecrickets.prudence.cache.HazelcastCache,
	com.threecrickets.prudence.cache.MongoDbCache)
​
// memcached: The constructor accepts a list of nodes (ports required)
component.context.attributes.put('com.threecrickets.prudence.cache',
	new MemcachedCache('127.0.0.1:11211, 192.168.1.12:11211'))
​
// Hazelcast: The configuration is in /configuration/hazelcast.conf
component.context.attributes.put('com.threecrickets.prudence.cache',
	new HazelcastCache())
​
// MongoDB
component.context.attributes.put('com.threecrickets.prudence.cache',
	new MongoDbCache())

Other Documents

Calling document.include is equivalent to using the include scriptlet, <%& … %>. Internally, the include scriptlet is turned into a regular scriptlet that calls document.include.

1. This mechanism allows you to divide your documents into fragments that you can re-use in many documents, helping you manage large applications and keep them consistent. Fragments can include other fragments, those can include others, etc. A common strategy is to separate the document header and footer into fragments and include these in all pages.
2. Because each document fragment can have its own caching properties, fragmentation is also an important strategy for fine-grained caching. It's important to keep in mind, though, that the outermost document's cacheDuration will override all others. If a cached version of a document is used, then it is not executed, which means that document.include calls in it are not executed, too.
3. Scriptlets in the fragments can include re-usable code, such as function and class definitions. You can thus use document.include to include code libraries. You might want to consider, though, using document.execute instead, as it will let you use regular source code documents and not have to use scriptlets.

The main difference between document.include and document.execute is that the former expects "text-with-scriptlets" documents, while the latter uses plain source code.

1. The executed code can be re-usable, such as function and class definitions. This allows you to treat it as a code library. Notes:
   1. For JavaScript and Groovy flavors: Prudence's document.execute is your only option for code inclusion in Prudence, because both JavaScript and Groovy do not have a code inclusion mechanism. Note that in many of these cases you are treating the code as a library, and are better off using document.executeOnce instead.
   2. In most cases, you would probably want to use your language's code inclusion mechanism instead of document.execute. For example, use "import" in Python, Ruby and PHP, and "require" in Clojure. The native inclusion mechanism might do a better job at caching code, managing namespaces, avoiding duplication, etc.
2. The executed code does not have to be in the same language as the calling code. This lets you use multiple languages in your applications, using the strengths of each. Note that languages cannot normally share function and class definitions, but can share state, via mechanisms such as application.globals, if the languages use compatible structures.
3. Use document.execute as an alternative to document.include if you prefer not to use scriptlets. For example, executing "mylibrary.js" might be more readable than including a fragment called mylibrary.html, if it is all just one JavaScript scriptlet.

1. By letting you use your REST resources both internally and externally, document.internal lets you create unified resource API. document.internal directly accesses the resource (not via HTTP), so it is just about as fast as a simple function call, and is definitely scalable. Thus, there may be no need to create a separate set of functions for you to use internally and HTTP resources for external clients to use. A unified API would minimize the possibility of bugs and add coherence to your code, by enforcing a RESTful architecture all around. A second advantage is that you could trivially make your API remote by running it on a different Prudence instance, and using document.external instead. This could allow for an easy way to run your application in a cluster, behind a load balancer.
2. You can create unit tests for your resources without having to start an HTTP server.
3. The preheating mechanism uses document.internal to load resources.

document.internal makes requests via the RIAP (Restlet Internal Access Protocol). You can construct URIs of this pseudo-protocol on your own, like so: "riap://application/myresource/". A call to document.external with this URI would be identical to calling document.internal with "/myresource/". See the Restlet documentation for full information about RIAP and other pseudo-protocols (CLAP, JAR, WAR, etc.).

1. You can add scale and redundancy to your internal REST API by running several Prudence instances behind a load balancer, and using document.external instead of document.internal.
2. You can use Prudence to create an internal communication backbone for your enterprise, with various backend services exposing resources to each other. You can expose the same resources to business partners, allowing for "B2B" (business-to-business) services.
3. There are many, many use cases for document.external, and they keep growing as REST is adopted by service providers on the Internet. There are online storage, publishing and content delivery systems, public databases, archives, geolocation services, social networking applications, etc. Perhaps, with Prudence, you will create the next one.

Important: The semantics of ClientResource require you to explicitly release the response as soon as you're done using it, which will in turn release the thread used to stream the response to you. (Though these threads might eventually be reclaimed by a built-in garbage collection mechanism, leaving them hanging could lead to starvation, such that further uses of document.external will block until threads return to the pool.) It's probably best to employ a try-finally paradigm, where the try clause contains as little code as possible, and the finally clause releases the response. See the example below.

var fixture
var resource = document.external('file:///myfiles/fixture.json', 'application/json')
try {
	fixture = resource.get().text
}
finally {
	resource.response.release()
}
​
// Do something with the fixture here...

In case you're interested, Prudence internally uses Apache's HTTP client for high-performance access to external HTTP documents, with full support for secure connections (prefixed with "https://").

executable

• executable.context.writer: direct access to the output writer (writes to a memory buffer in /web/dynamic/, and to standard output in /resources/, /handlers/, /tasks/ and configuration scripts)
• executable.context.exposedVariables: Prudence services are here (application, document, executable, conversation)
• executable.context.attributes: for use by the language engines

conversation

Note that in /web/dynamic/ "conversation" is available as a global variable. In /resources/ and /handlers/, it is sent to the handling entry points (functions, closures, etc.) as an argument. Usage is otherwise identical. "conversation" is not available in configuration scripts or in /tasks/.

The Request

• conversation.reference.identifier: the complete URI
• conversation.reference.path: the URI, not including the domain name and the query matrix
• conversation.reference.segments: a list of URI segments in the path
• conversation.reference.lastSegment: the last segment in the URI path
• conversation.reference.fragment: the URI fragment (whatever follows "#")
• conversation.reference.query: the URI query (whatever follows "?"); you might prefer to use conversation.query instead
• conversation.reference.relativeRef: a new reference relative to the base URI (usually the application root URI on the current virtual host)

Click <a href="<%= conversation.pathToBase %>/contact/">here</a> to contact us.

Note: If you are caching a document that relies on conversation.pathToBase, you likely also want to include "{ptb}" or some other path reference in the document.cacheKeyPattern.

• data: the raw data as an array of bytes, for uploaded files stored in memory
• file: a JVM File instance, for files stored on disk; uploaded files are stored in the application's /uploads/ subdirectory
• size: in bytes
• mediaTypeName: the MIME type set by the client, such as "image/jpeg"
• mediaType: the MediaType instance equivalent to the above, if available

• conversation.entity.size: the size of the data in bytes, or -1 if unknown
• * conversation.entity.text: the data as text (only useful if the data is textual)
• * conversation.entity.reader: an open JVM Reader to the data (only useful if the data is textual)
• * conversation.entity.stream: an open JVM InputStream to the data (useful for binary data)

Note: Client data is provided as a stream that can only be "consumed" once. Attributes that cause consumption are marked with a "*" above. Note that conversation.entity.text is one of them! If you want to access conversation.entity.text more than once, save it to a variable first.

The Response

If the client does not specify a preferred character set, then the character set will fall back to a default determined by the "com.threecrickets.prudence.GeneratedTextResource.defaultCharacterSet" application global. It not explicitly set, it will be UTF-8.

conversation.disposition.type = 'attachment'
conversation.disposition.filename = 'revenue.csv'

conversation.headers.add('X-Pingback', 'http://mysite.org/pingback/')

Cookies

• cookie.name: (read only)
• cookie.version: (integer) per a specific cookie.name
• cookie.value: textual, or text-encoded binary data (note that most clients have strict limits on how much total data is allowed to be stored in all cookies per domain)
• cookie.domain: the client should only use the cookie with this domain and its subdomains (web browsers will not let you set a cookie for a domain which is not the domain of the request or a subdomain of it)
• cookie.path: the client should only use the cookie with URIs that begin with this path ("/" would mean to use it with all URIs)

• cookie.maxAge: age in seconds, after which the client should delete the cookie. maxAge=0 deletes the cookie immediately, while maxAge=-1 (the default) asks the client to keep the cookie only for the duration of the "session" (this is defined by the client; for most web browsers this means that the cookie will be deleted when the browser is closed).
• cookie.secure: true if the cookie is meant to be used only in secure connections (defaults to false)
• cookie.accessRestricted: true if the cookie is meant to be used only in authenticated connections (defaults to false)
• cookie.comment: some clients store this, some discard it

Conditional Requests

Client Caching

Resource Initialization

Conversation Flow

1. The document.internal API
2. URI capturing

if(conversation.defer()) {
	conversation.stop()
}

This is an experimental feature in Prudence 1.1. The use of a separate thread pool is only supported when using the internal Restlet connector. For other connectors (such as Jetty, the default), a successful call to defer will cause the page to be executed again in the same thread.

Low-level Access

Sharing State

conversation.locals

1. To easily share conversation-scope state between scriptlets written in different languages.
2. To share state for deferred conversations—see conversation.defer. In such cases, your language's globals would not persist across the thread boundaries.
3. They are Prudence's general mechanism for sending state to your code in a conversation. For example, captured URI segments are stored here as well as document.cacheKeyPattern variables.

Global Variables

The exception to this is code in /resources/, in which language globals might persist. To improve performance, Prudence caches the global context for these in memory, with the side effect that your language globals persist beyond a single user request. For various reasons, however, Prudence may reset this global context. You should not rely on this side effect, and instead always use application.globals.

application.globals vs. application.sharedGlobals

1. To save resources. For example, if an application detects that a database connection has already been opened by another application in the Prudence instance, and stored in application.sharedGlobals, then it could use that connection rather than create a new one. This would only work, of course, if a few applications share the same database, which is common in many deployments.
2. To send messages between applications. This would be necessary if operations in one application could affect another. For example, you could place a task queue in application.sharedGlobals, where applications could queue required operations. A thread in another application would consume these and act accordingly. Of course, you will have to plan for asynchronous behavior, and especially allow for failure. What happens if the consumer application is down? It may make more sense in these cases to use a persistent storage, such as a database, for the queue.

Note for Clojure flavor: All Clojure vars are VM-wide globals equivalent in scope to executable.globals. You usually work with namespaces that Prudence creates on the fly, so they do not persist beyond the execution. However, if you explicitly define a name space, then you can use it as a place for shared state. It will then be up to you to make sure that your namespace doesn't collide with that of another application installed in the Prudence instance. Though this approach might seem to break our rule of thumb here, of preferring application.globals to application.sharedGlobals, it is more idiomatic to Clojure and Lisps more generally.

application.sharedGlobals vs. executable.globals

Concurrency

Note for Clojure flavor: Though Clojure goes a long way towards simplifying concurrent programming, it does not solve the problem of concurrent access to global state. You still need to read this section!

def get_connection()
	data_source = application.globals['myapp.data.source']
	if data_source is None:
		data_source = data_source_factory.create()
		application.globals['myapp.data.source'] = data_source
	return data_source.get_connection()

This may seem like a very rare occurrence to you: another thread would have to set the value exactly between our comparison and our set. If your application has many concurrent users, and your machine has many CPU cores, it can actually happen quite frequently. And, even if rare, your application has a chance of breaking if just two users use it at the same time. This is not a problem you can gloss over, even for simple applications.

def get_connection()
	data_source = application.globals['myapp.data.source']
	if data_source is None:
		data_source = data_source_factory.create()
		data_source = application.getGlobal('myapp.data.source', data_source)
	return data_source.get_connection()

def get_connection()
	lock = application.getGlobal('myapp.data.source.lock', RLock())
	lock.acquire()
	try:
		data_source = application.globals['myapp.data.source']
		if data_source is None:
			data_source = data_source_factory.create()
			application.globals['myapp.data.source'] = data_source
		return data_source.get_connection()
	finally:
		lock.release()

def get_connection(lock_access=False)
	if lock_access:
		lock = application.getGlobal('myapp.data.source.lock', RLock())
		lock.acquire()
	try:
		data_source = application.globals['myapp.data.source']
		if data_source is None:
			data_source = data_source_factory.create()
			if lock_access:
				application.globals['myapp.data.source'] = data_source
			else:
				data_source = application.getGlobal('myapp.data.source', data_source)
		return data_source.get_connection()
	finally:
		if lock_access:
			lock.release()