Implementing Resources

Programmable Resources

• Resources can be implemented using any of the supported programming languages.
• Uncaught exceptions in any entry point or scriptlet will result in the conversation ending and a 500 ("internal server error") HTTP status code returned to the user. To help you debug these errors, turn on debug mode, which will enable a detailed debug representation. Otherwise, you can set up a custom error page, or, in the last resort, a simple error page will be shown, that at least notifies the user that something went wrong.
• Your source code is parsed/compiled on-the-fly only when necessary. A reparsing/recompilation is triggered when the file is modified, or when any of its dependent files are modified. To keep track of dependencies at any distance, Prudence internally maintains a dependency tree for each document. Note that checking for file modification dates involves an operating system API call: the call is usually cached by the OS and very fast, however you can configure the minimum time between validity checks if necessary.
• If you've captured a URI template, you can access the captured parts of the template via conversation.locals or conversation.wildcard.

Manual Resources

• Resource mapping: Here, the entry points are in the global scope, probably defined within the file, though they can be imported via a library or created programmatically (as closures, for example). What an "entry point" means exactly may vary per programming language: it's usually a function, method, closure, etc. See the programming guide for examples in all supported languages.
• Resource dispatching: The default dispatchers attempt an object-oriented encapsulation, which again varies per programming language. The dispatch ID defines an object instance, which must in turn implement the entry points.

Configuration

app.routes = {
	'/*': 'manual'
}

app.routes = {
	'/*': {
		type: 'manual',
		root: 'resources',
		passThroughs: [],
		preExtension: 'm',
		trailingSlashRequired: true,
		internalUri: '/_manual/',
		clientCachingMode: 'conditional',
		maxClientCachingDuration: -1,
		compress: true
	}
}

handleInit

function handleInit(conversation) {
	conversation.addMediaTypeByName('application/json')
	conversation.addMediaTypeByName('text/plain')
}

function handleInit(conversation) {
	conversation.addMediaTypeByNameWithLanguage('text/plain', 'en')
	conversation.addMediaTypeByNameWithLanguage('text/plain', 'fr')
}

function handleInit(conversation) {
	conversation.addMediaTypeByName('application/xml')
	caching.duration = '5s'
	caching.tags.add('blog')
}

handleGet

• Numbers: Returns the number as an HTTP status code to the client. If you you wish to set your own return representation, too, you can use conversation.setResponseText or conversation.setResponseBinary. Note that if the status code is an error, then the error capturing mechanism may override your response. If you wish to bypass this mechanism, set conversation.statusPassthrough to true.
• Arrays of bytes: Used for returning binary representations. Note that some languages (JavaScript, for example) have their own implementations of arrays, which are not compatible with JVM arrays. In such cases, you have to make sure to return JVM arrays. Internally, Prudence represents these values with a ByteArrayRepresentation.
• Representation instances: You can construct and return a directly.
• Other return values: If the conversation.mediaType is "application/internal" then the value will be wrapped in an InternalRepresentation. Otherwise, it will be converted into a string if it isn't a string already, and returned to the client as a StringRepresentation.

handlePost

The most important thing to realize is that POST is the only HTTP operation that is not "idempotent," which means that multiple identical POST operations on a resource may yield results that are different from that of a single POST operation. This is why web browsers warn you if you try to refresh or go back to a web page that is the result of a POST operation. As such, POST is the correct operation to use for manipulations of a resource that cannot be repeated. So, if you're thinking in terms of CRUD, POST can mean either "update" or "create": it depends on whether or not "create" is a repeatable operation in your specific data semantics. See this blog post by John Calcote for one explanation.

handlePut

PUT, like most HTTP operations, is "idempotent," which means that multiple identical PUT operations on a resource are expected to yield the same result as a single PUT operation. PUT should thus overwrite any existing data. If you are implementing a "create" operation that cannot be repeated, then you should use POST instead. See note in POST.

handleDelete

• Null: Signifies success.
• Number: Returns the number as an HTTP status code to the client, with no other content: for example, returning 404 means "not found." Note that error capturing can let you take over and return an appropriate error page to the client.

Though some languages return null if no explicit return statement is used, others return the value of the last executed operation, which could be a number, which would in turn become an HTTP status code for the client. This can lead to some very bizarre bugs, as clients receive apparently random status codes! It's thus good practice to always explicitly return null in handleDelete, if only to add clarity to your code's intent.

handleGetInfo

• Null: Means that you wish to continue directly to handleGet.
• Numbers or JVM Date instances: Considered as Unix timestamps, and converted into the modification date.
• Strings or Tag instances: Considered as HTTP tags.
• RepresentationInfo instances: Returned as is.

Template Resources

The "scriptlets" parser is intended to be as straightforward and flexible as possible, mimicking the familiar paradigm of PHP/ASP/JSP, which allows for raw code that is executed in-place. However, it's possible to replace this parser with your own should you desire. For example, you might prefer declarative rather than procedural templates (mimicking the structure of HTML/XML), and rather than have opaquely delimited areas, you might prefer structural parsing of XML attributes. The parser system is pluggable and easy to extend.

Configuration

app.routes = {
	'/*': 'templates'
}

app.routes = {
	'/*': {
		type: 'templates',
		root: 'resources',
		includeRoot: ['libraries', 'includes'],
		passThroughs: [],
		preExtension: 't',
		trailingSlashRequired: true,
		defaultDocumentName: 'index',
		defaultExtension: 'html',
		clientCachingMode: 'conditional',
		maxClientCachingDuration: -1,
		compress: true
	}
}

MIME Types and Compression

Scriptlets

<% for (var x = 0; x < 10; x++) { %>
<p>This is a "line"</p>
<% } %>

for (var x = 0; x < 10; x++) {
print("<p>This is a \"line\"</p>")
}

It's important to emphasize that any code can be used in templates: you can import libraries, define functions and classes, etc. It's up to you to decide how much and what kind of programming logic to use in templates. There are indeed strict coding disciplines, such as MVC, that forbid anything but visual logic in template. See the MVC chapter for a complete discussion.

<%ruby print 1 + 2 %>

Built-In Shortcuts

<%= x*2 %>

<% print(x*2) %>

<%& '/header/' %>

<% document.include('/header/'); %>

<%.%>

<%# This scriptlet will be ignored by the parser. %>

<%=rb x*2 %>

Fragments

<li><%= line %></li>

<% for (int l in lines) { var line = lines[l] %>
<%& '/lists/simple/' %>
<% } %>

Fragments in Prudence are not merely "server-side includes": in fact, each fragment is cached separately, with its own cache key and cache duration. This allows you to create sophisticated and extremely efficient fine-grained caching strategies. See the caching chapter.

Blocks and Inheritance

<%{ title %>
	<h1>My Title</h1>
<%}%>
<%& '/templates/main/' %>

<html>
<body>
<%== title %>
</body>
</html>

<html>
<body>
<%[ title %>
	<h1>Default Title</h1>
<%]%>
</body>
</html>

<% function header1(content) { %>
<h1><%= content %></h1>
<% } %>

<% header1('Hello'); %>

<%{ myArgument %>
<a href="/">This HTML code will be sent as an argument</a>
<%}%>
<% header1(conversation.locals.get('myArgument')); %>

Templating Languages

<%js
conversation.locals.put('test', 'TEST')
%>
<%velocity
#macro(hello $name)
	<div>Hello, $name!</div>
#end
<div>
	#hello('Mozart')
	#hello('Bach')
	Here is a conversation local: $!conversation.locals.test
</div>
%>

sincerity add velocity : install

HTML Markup Languages

<html>
<body>
<%md
​
Our Conference
==============
​
* The first item of business
* The second item of business
​
%>
</body>
</html>

sincerity add org.pegdown pegdown : install

PHP

<?php
for($i = 0; $i < 10; $i++) {
	print '<p>' . $i . '</p>';
}
?>

<?php
print $_GET['id']
?>

app.settings = {
	...
	mediaTypes: {
		php: 'text/html'
	}
}

Scriptlet Plugins

app.settings = {
	...
	templates: {
		plugins: {
			'_': '/plugins/custom/',
			'&?': '/plugins/custom/'
		}
	}
}

function handleGetScriptlet(code, languageAdapter, content) {
	if (code == '_') {
		return "print(application.globals.get('text.' + conversation.locals.get('locale') + '." + content.trim() + "'));"
	}
	else if (code == '&?') {
		return "if(conversation.locals.get('include')===true) { document.include(" + content + ") }"
	}
	return ''
}

<%
conversation.locals.put('locale', 'en')
conversation.locals.put('include', false)
%>
<p>
	How to say "hello" in your language: <%_ basic.hello %>
</p>
<p>
	This fragment will not be included: <%&? '/hello/' %>
</p>

app.globals = {
	text: {
		en: {
			basic: {
				hello: 'Hi!'
			}
		},
		es: {
			basic: {
				hello: '¡Hola!'
			}
		}
	}
}

• It's up to you, of course, to make sure that the code you generate is compilable.
• Plugins are tested for before the built-in shortcuts, allowing you to override the built-in ones.
• If you change your plugin code, it will not cause all template resources that use it to recompile. To force a recompile, you will need to change the modification date of those files, possibly by using the "touch" tool (on *nix).

Static Resources

Configuration

app.routes = {
	'/*': 'static'
}

app.routes = {
	'/*': {
		type: 'static',
		roots: [
			'resources',
			sincerity.container.getLibrariesFile('web')
		],
		listingAllowed: false,
		negotiate: true,
		compress: true
	}
}

app.routes = {
	'/*': [
		{type: 'static', root: 'resources'},
		{type: 'static', root: sincerity.container.getLibrariesFile('web')}
	]
}

app.routes = {
	'/*': [
		'manual',
		'templates',
		'static'
	]
}

MIME Types and Compression

Client-Side Caching

app.routes = {
	'/*': {
		type: 'cacheControl',
		mediaTypes: {
			'image/*': '10m',
			'text/css': '10m',
			'application/x-javascript': '10m'
		},
		next: 'static'
	}
}

<img src="/media/logo.png" />

<img src="/media/logo.png?_=1" />

app.routes = {
	'/*': {
		type: 'cacheControl',
		mediaTypes: {
			'image/*': 'farFuture'
		},
		next: 'static'
	}
}

What happens to cache entries that have been marked to expire in 10 years, but are no longer used by your site? They indeed will linger in your client's web browser cache. This isn't too bad: web browsers normally are configured with a maximum cache size and the disk space will be cleared and reused if needed. It's still an inelegant waste, for which unfortunately there is no solution in HTTP and HTML.

JavaScript and CSS Optimization

app.routes = {
	'/*': {
		type: 'javaScriptUnifyMinify',
		next: 'static'
	}
}

app.routes = {
	'/*': {
		type: 'javaScriptUnifyMinify',
		roots: [
			'resources/scripts',
			sincerity.container.getLibrariesFile('web', 'scripts')
		],
		next: 'static'
	}
}

/resources/scripts/jquery.js
/resources/scripts/jquery.highlight.js
/resources/scripts/jquery.popup.js

<head>
	...
	<script src="/scripts/all.min.js"></script>
</head>

app.routes = {
	'/*': {
		type: 'javaScriptUnifyMinify',
		next: {
			type: 'cssUnifyMinify',
			next: 'static'
		}
	}
}

<head>
	...
	<link rel="stylesheet" type="text/css" href="/style/all.min.css" />
</head>

LESS to CSS

app.routes = {
	'/*': {
		type: 'less',
		next: 'static'
	}
}

<head>
	...
	<link rel="stylesheet" type="text/css" href="/style/dark/main.min.css" />
</head>

See the FAQ as to why Prudence supports LESS but not SASS.

Other Effects

function handleAfter(conversation) {
	var entity = conversation.response.entity
	if (entity.mediaType.name == 'application/pdf') {
		entity.disposition.type = 'attachment'
	}
}

app.routes = {
	'/*': {
		type: 'filter',
		library: '/filters/download-pdf/',
		next: 'static'
	}
}

On-the-Fly Resources

Diligence comes with the console feature, which offers a user-friendly variation of this functionality: it's a web-based mini-IDE that features persistent programs, JavaScript syntax coloring, and log tailing/filtering.

app.routes = {
	...
	'/execute/': 'execute'
}

Because it allows execution of arbitrary code, you very likely do not want its URL publicly exposed. Make sure to protect its URL on publicly available machines!

curl --data '<% println(1+2) %>' http://localhost:8080/myapp/execute/

curl --data-binary @myscriptfile http://localhost:8080/myapp/execute/

<%
document.require('/sincerity/templates/')
println(Hello, {0}'.cast('Linus'))
%>

<%
document.require('/sincerity/templates/')
var name = conversation.query.get('name') || 'Linus'
println('Hello, {0}'.cast(name))
%>

curl --data-binary @myscriptfile 'http://localhost:8080/myapp/execute/?name=Richard'

<%python
name = conversation.query['name'] or 'Linus'
print 'Hello, %s' % name
%>

<%
document.require('/sincerity/json/')
conversation.mediaTypeName = 'application/json'
println(Sincerity.JSON.to({greeting: 'Hello'}, true))
%>

Java Resources

• Sure, Java can offer better performance than dynamic languages, but it's very rare for language performance to be the bottleneck: communication with a database server, for example, is orders of magnitude slower. Don't "drop down" to Java in order to optimize unless you've really confirmed that language performance is a problem.
• Prudence's manual resources are not merely dynamic-language implementations of ServerResource, but also provide extra features such as integrated server-side caching. If you switch to Java, you would have to implement such features on your own.

Resource Type Comparison Table

The Prudence Manual is provided for you under the terms of the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. The complete manual is available for download as a PDF.