Resources

Files

Life

Source Code

Global Source Code

• Global variables are not kept or shared between file updates, which cause the file to be reloaded, recompiled, and thus re-executed. Use application.globals instead.
• The re-execution mentioned above can cause your services to be re-initialized. This can be very undesirable, because the service previously initialized may not have been released. It can even lead to errors. It's thus a good idea to first check if the service has already been initialized. Storing references in application.globals is a great way to keep track of this.

API

Code Libraries

• Python:

  from util.data import getData
  data = getData()
  

• Ruby:

  require 'util/data.rb'
  $data = get_data
  

• Clojure:

  (use 'util.data)
  (def data (get-data))
  

• PHP:

  require 'util/data.php';
  $data = get_data();
  

• JavaScript and Groovy do not have a built-in code inclusion mechanism, but they can use Prudence's document.execute API:

  document.execute('/util/data/')
  data = getData()
  

Entry Points

What Are Entry Points?

• Python uses global functions:

  def handle_get(conversation):
  	return 'Hello, world!'
  

• Ruby uses global methods:

  def handle_get conversation
  	return 'Hello, world!'
  end
  

• Clojure uses functions in the current namespace:

  (defn handle-get [conversation]
  	'Hello, World!')
  

• JavaScript uses global functions:

  function handleGet(conversation) {
  	return 'Hello, world!'
  }
  

• PHP uses global functions:

  function handle_get($conversation) {
  	return 'Hello, World!';
  }
  

• Groovy uses closures tied to global variables (there are no global methods in Groovy):

  handleGet = { conversation ->
  	return 'Hello, World!'
  }
  

handleInit

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

handleGet

• Numbers: Returns the number as an HTTP status code to the client, with no other content. Usually used for errors. For example, 404 means "not found." Note that error capturing can let you take over and return an appropriate error page to the client.
• Arrays of bytes: Used for returning binary representations. Note that some languages (JavaScript, for example) have their own implementations of arrays, which are not exactly 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 Restlet representation directly.
• Other return values: If the conversation.mediaType is "application/java" the value will be wrapped in an ObjectRepresentation instance. Otherwise, it will be converted into a string if it isn't a string already, and returned to the client as a textual representation.

handlePost

POST is the only HTTP operation that is not "idempotent," which means that multiple identical POST operations on a resource may yield different results from a single POST operation. This is why web browsers warn you if you try to refresh 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. See this blog post by John Calcote for an in-depth 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. If you are implementing a "create" operation that cannot be repeated, then you should use POST instead. See note in POST.

handleDelete

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

Note: It's good practice to always explicitly return null in handleDelete. Some languages return null if no explicit return statement is used. Others, however, 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!

handleGetInfo

• Numbers: Considered as Unix timestamps, and converted into the modification date. See conversation.modificationDate.
• JVM Date instances: The modification date. Refer to the Java API documentation for details.
• Strings: Considered as HTTP tags. See conversation.tag.
• Tag instances: You can construct and return your own Restlet tag.
• RepresentationInfo instances: You can construct and return your own Restlet representation info.

1. It could be that you don't need this optimization. Make sure, first, that you've actually identified a problem with performance or scalability, and that you've traced it to handleGet on this resource.
2. It could be that you won't gain anything from this optimization. Caches and other optimizations along the route between your data and your client might already be doing a great job at keeping handleGet as efficient as it could be. If not, improving them could offer far greater benefits overall than a handleGetInfo.
3. It could be that you'll even hurt your scalability! The reason is that an efficient handleGetInfo implementation would need some mechanism in place to track of data modification, and this mechanism can introduce overhead into your system that causes it to scale worse than without your handleGetInfo.

Conditional Requests

Resources As API

function handleInit(conversation) {
	conversation.addMediaTypeByName('application/json')
	conversation.addMediaTypeByName('application/java')
}
​
function handleGet(conversation) {
	var data = getData()
	if(conversation.mediaTypeName == 'application/java') {
		return data
	}
	else {
		return JSON.to(data)
	}
}
​
function getData() {
	return {name: 'test', description: 'This is some test data'}
}

var data = document.internal('/testme/', 'application/java').get().object
print(data.description)
​
// Just for comparison, here's how we would to it using JSON encoding/decoding
var data = eval('(' + document.internal('/testme/', 'application/json').get().text + ')')
print(data.description)

Note: The "application/java" media type can be used externally, too. In such a case, the object would be serialized/unserialized over HTTP. This does mean that your data class has to properly support JVM serialization, via the Serializable or Externalizable interfaces.