Sandbox Discovery

Each Zamples server is configured by the administrator, who defines the language sandboxes and assigns a unique numeric ID and an alphanumeric language code to each language sandbox.  Before a client can execute a code example, it must specify the sandbox ID or sandbox code along with the code to be executed.  There are two types of queries with return the same information, but presented differently.  The plain text query is quick and easy to parse, but requires that you write a program for the returned data.  The XML query takes longer to parse, but many XML libraries will automatically parse the data and return a collection of objects.

There will always be at least three sandboxes defined because the HTML or JSP Fragment, Java Servlet Fragment and HTML and Applet sandboxes are hardwired.  All other sandboxes are defined in the Zamples sandbox configuration file (Zamples administrators know this as dispatch.properties).

Plain Text Query

You can easily discover the active sandboxes defined for a specific Zamples server by an HTTP GET or POST to /JspExplorer/zamples/discover/.  The results are returned as a text/plain page.  The default imports, cmd and applet lines are HTML encoded.  As with all Zamples REST calls, the common Zamples REST parameters must be specified.

In the following example, replace myUid with your Zamples user id and myPwd with your Zamples password.

<a href=/JspExplorer/zamples/discover?clientUser=myUid&clientPassword=myPwd>Discover</a> 
the Zamples language sandboxes on this Zamples server 
by clicking on the link.

Typical Output

The sections are color-coded for your convenience.

1. Version number of the Zamples Client Specification that this Zamples server implements
2. Number of active language sandboxes
3. Language IDs
4. Short form of the sandbox names
5. Displayable names of the sandboxes
6. Default values for imports (or command line parameters)
7. Default values for cmd
8. Default values for applet (usually ignored, except for applets)

You don't have to use all the languages in your client - discovery only shows you what you have to work with for that particular Zamples installation. The HTML-encoded lines of the last three sections of the following output have been truncated for clarity (default values for imports, cmd and applet.)

0.8beta4
8
0
2
3
10
15
20
25
4608
jsp
javaFragment
applet
jdk14
jdk14cl
jdk15
jdk15cl
csharp
HTML or JSP Fragment
Java Servlet Fragment
HTML and Applet
JDK 1.4 Fragment
JDK 1.4 Class
JDK 5.0 Fragment
JDK 5.0 Class
C# (Mono)
// Type the names of packages to be imported here,
// ...
// Type the names of packages to be imported here,
// ...
// No imports are needed in a JSP that loads an applet
// Put import statements here
Zamples says it is now <%=new java.util.Date()%>.
out.println("Zamples says it is now " + new java.util.Date());
<!-- Do not change the next three lines -->
<APPLET
 &...
System.out.println("I love zamples!!!!");
// This is a text area for applet Java code.
// Ignore this...
// This is a text area for applet Java code.
// Ignore this...
// Do not change <%=appletName()%> in the next line.
...
// This is a text area for applet Java code.
// Ignore this...

The above output shows that eight language sandboxes are defined, as shown in this table:

The third column above (Sandbox Name) is not stored with the code example, so your client may display something different, for example, you can display the Sandbox Name in a different language.

Some languages, such as Java, have two similarly named sandboxes - one that requires complete programs, and one that accepts code fragments and wraps them in a main() method.  Zamples convention is to indicate the sandboxes which require entire programs in 'cl'.  For example, JDK 1.4's sandboxes are called jdk14 (for code fragments) and jdk14cl for (entire programs).  Sandbox names are case sensitive.

XML Query

You can use REST to retrieve the same information in an XML format.  The results are returned as a application/xml; charset=UTF-8 page.  In the following example, replace myUid with your Zamples user id and myPwd with your Zamples password.

<a href=/JspExplorer/zamples/discoverRest?clientUser=myUid&clientPassword=myPwd>Discover</a> 
the Zamples language sandboxes on this Zamples server 
by clicking on the link.

Typical Output

For clarity, the default values for imports, cmd and applet are not shown.  These values are not encoded.

<?xml version="1.0"?>
<sandboxes number="8" version="0.8beta4">
   <sandbox id="0" code="jsp" name="HTML or JSP Fragment">
       <defaultImports><![CDATA[...]]></defaultImports>
       <defaultCmd><![CDATA[...]]></defaultCmd>
       <defaultApplet><![CDATA[...]]></defaultApplet>
   </sandbox>
   <sandbox id="2" code="javaFragment" name="Java Servlet Fragment">
       <defaultImports><![CDATA[...]]></defaultImports>
       <defaultCmd><![CDATA[...]]></defaultCmd>
       <defaultApplet><![CDATA[...]]></defaultApplet>
   </sandbox>
   <sandbox id="3" code="applet" name="HTML and Applet">
       <defaultImports><![CDATA[...]]></defaultImports>
       <defaultCmd><![CDATA[...]]></defaultCmd>
       <defaultApplet><![CDATA[...]]></defaultApplet>
   </sandbox>
   <sandbox id="10" code="jdk14" name="JDK 1.4 Fragment">
       <defaultImports><![CDATA[...]]></defaultImports>
       <defaultCmd><![CDATA[...]]></defaultCmd>
       <defaultApplet><![CDATA[...]]></defaultApplet>
   </sandbox>
   <sandbox id="15" code="jdk14cl" name="JDK 1.4 Class">
       <defaultImports><![CDATA[...]]></defaultImports>
       <defaultCmd><![CDATA[...]]></defaultCmd>
       <defaultApplet><![CDATA[...]]></defaultApplet>
   </sandbox>
   <sandbox id="20" code="jdk15" name="JDK 5.0 Fragment">
       <defaultImports><![CDATA[...]]></defaultImports>
       <defaultCmd><![CDATA[...]]></defaultCmd>
       <defaultApplet><![CDATA[...]]></defaultApplet>
   </sandbox>
   <sandbox id="25" code="jdk15cl" name="JDK 5.0 Class">
       <defaultImports><![CDATA[...]]></defaultImports>
       <defaultCmd><![CDATA[...]]></defaultCmd>
       <defaultApplet><![CDATA[...]]></defaultApplet>
   </sandbox>
   <sandbox id="4608" code="csharp" name="C# (Mono)">
       <defaultImports><![CDATA[...]]></defaultImports>
       <defaultCmd><![CDATA[...]]></defaultCmd>
       <defaultApplet><![CDATA[...]]></defaultApplet>
   </sandbox>
</sandboxes>

Standard Sandbox Definitions

Here are the standard definitions for language sandboxes.  Again, the default values for imports, cmd and applet are not shown.

Possible error messages

In addition to the common Zamples REST error status codes, this Zamples REST call can generate the following error statuses and messages: