Querying Code Examples in a Knowledge Base
When an empty threaded discussion is displayed and a user clicks on a New button and saves a new posting,
the threaded discussion will incorporate the user's posting each time it is displayed thereafter.
To retrieve postings with embedded code examples from a Zamples server,
make a REST call.
Form your query from zero or more of the following parameters.
These case-sensitive parameters filter fragment records from the knowledge base.
You may use GET parameters and/or POST parameters.
GET parameters must be URL-encoded.
Don't forget the common Zamples REST parameters must also be specified.
| Parameter name |
Meaning |
| kb |
KnowledgeBase or book name |
| package |
Package or chapter name. Defaults to the empty string. |
| class |
Class or section name. Defaults to the empty string. |
| method |
Method/function or subsection name |
| sandbox |
sandbox code. Defaults to jsp. |
| created |
milliseconds since 1970 (date/time code example was posted).
Defaults to the time that the REST call is made. |
| open |
Boolean flag to indicate if this is a support request that has been resolved.
Defaults to true. |
| example |
Boolean flag to indicate if this posting has been quality checked.
Defaults to false. |
| user |
User handle of person who posted the code example |
| start |
Index of first posting to retrieve (used with count to page through numerous postings).
Defaults to 1. |
| count |
Maximum number of postings to retrieve.
Specifying this parameter causes matches to be set to.
Default is 50. |
The results are returned as a text/plain page.
The following elements are returned with the Postings element:
| Attribute name |
Meaning |
| start |
The start attribute of the Postings element matches the start parameter passed via the URL query, or is zero if the attribute was not specified |
| count |
Indicates the number of examples returned. |
| matches |
The matches attribute indicates the total number of postings that matched the query. The Zamples server may be configured to cap the maximum number of search results returned from a query (the default cap is 50), so the response's count attribute might be less than the value of the count parameter specified in the query. |
The following elements and attributes are returned with each Posting element:
| Name |
Javadoc/structured documentation usage |
Book usage |
| kb |
KnowledgeBase name |
Book name |
| package |
Package name |
Chapter name |
| class |
Class name |
Section name |
| method |
Method/function name |
Subsection name |
| ranges |
Specifies lines of code to display to the user. |
| sandbox |
Sandbox for executing the code example |
| created |
Milliseconds since 1970 (date/time code example was posted) |
| open |
Boolean flag to indicate if this is a support request that has been resolved |
| example |
Boolean flag to indicate if this posting has been quality checked |
| user |
User handle of person who posted the code example |
To retrieve all postings related to a threaded discussion, specify
knowledge base name, package name, class name and method name,
The following query retrieves all code examples for a specific
Javadoc threaded discussion (line folded for clarity):
http://zamples.com/JspExplorer/zamples/kbSearch?kb=MyAPI&package=MyPackage& 
class=MyClass&method=MyMethod()&clientUser=myUid&clientPassword=myPwd
Here is a live code example that does the same thing, but passes the parameters in a form.
After you run the code example, click the Submit Query button to execute the query.
Be sure to edit the values of the hidden parameters, especially clientUser and clientPassword, then press
Run it! in order to recreate the Submit Query button
with the new settings.
|
<form action=/JspExplorer/zamples/kbSearch>
<input type=hidden name=kb value=MyAPI>
<input type=hidden name=package value=MyPackage>
<input type=hidden name=class value=MyClass>
<input type=hidden name=method value=MyMethod()>
<input type=hidden name=clientUser value=myUid>
<input type=hidden name=clientPassword value=myPwd>
<input type=submit>
</form> |
A typical response might be (shortened to only one record, and folded for clarity):
<?xml version="1.0"?>
<Postings start="0" count="1" matches="141">
<Posting id="12254" created="1107931589000" notify="true" pre="true" priority="3" sandbox="jdk14"
userId="fflintstone" closed="false" example="true" stylesheet="false"
kbName="Amazon Web Services" packageName="tutorial"
className="default" methodName="1">
<applet><![CDATA[]]></applet>
<cmd><![CDATA[>AmazonSearchPort port = null; AmazonSearchService service 
= new AmazonSearchServiceLocator(); try {     
port = service.getAmazonSearchPort(); } catch 
(javax.xml.rpc.ServiceException e) { e.printStackTrace(); }
KeywordRequest req = new KeywordRequest(); try {  
  req.setKeyword(java.net.URLEncoder.encode("web services", "
utf-8")); } catch (java.io.UnsupportedEncodingException ignored) {}
req.setMode("books"); req.setType("lite");
ProductInfo res = null; try {     res 
= port.keywordSearchRequest(req); } catch (Exception e) { 
e.printStackTrace(); } Details[] details = res.getDetails();
for (int i = 0; i < details.length; i++)
 {     String resultTitle = details[i].getProductName();
    System.out.println(i + ": " + 
resultTitle); }]]></cmd>
<topic><![CDATA[sports:bungie jumping:best underwear]]></topic>
<imports><![CDATA[import 
com.amazon.soap.axis.*;]]></imports>
<ranges><![CDATA[]]></ranges>
<subject><![CDATA[Simple Search using Java (take 2)]]></subject>
<purpose><![CDATA[If only I had a brain]]></purpose>
<description><![CDATA[At least life on autopilot is stress-free!]]></description>
</Posting>
</Postings>
Here is a similar request, which will return only the eleventh result using the start and count parameters:
|
<form action=/JspExplorer/zamples/kbSearch>
<input type=hidden name=count value=1>
<input type=hidden name=start value=11>
<input type=hidden name=kb value=MyAPI>
<input type=hidden name=package value=MyPackage>
<input type=hidden name=class value=MyClass>
<input type=hidden name=method value=MyMethod()>
<input type=hidden name=clientUser value=myUid>
<input type=hidden name=clientPassword value=myPwd>
<input type=submit>
</form> |
If retrieving a threaded discussion from Javadoc postings, be sure to
include the full signature of the method. Examine the HTML source for a Javadoc web page and note the format of the <a name>
tags next to method names if you have any doubts as to what the
proper method signature might be. Spaces are significant.
If the knowledge base you are working with does not reference Javadoc, but is intended to annotate a book divided into chapters, sections and subsections,
assign a unique string suggestive of the chapter name to the package name,
assign a unique string suggesting of the section name to the class name,
and assign a unique string to the method/subsection name as well. For example (line folded for clarity):
http://zamples.com/JspExplorer/zamples/kbSearch?kb=MyBook&package=Chapter1&class=Section1&method=Example1
&clientUid=myUid&clientPassword=myPwd
Here is another live code example that does the same thing as the first example above, but passes the parameters in a form.
After you run the code example, click the Submit Query button to execute the query:
|
<form action=/JspExplorer/zamples/kbSearch>
<input type=hidden name=kb value=MyBook>
<input type=hidden name=package value=Chapter1>
<input type=hidden name=class value=Section1>
<input type=hidden name=method value=Example1>
<input type=hidden name=clientUser value=myUid>
<input type=hidden name=clientPassword value=myPwd>
<input type=submit>
</form> |
In either case, the response from the Zamples server will be XML.
The attributes present in the Postings element will
result from the URL query parameters:
<?xml version="1.0"?>
<Postings start="1 count="2" matches="2">
<Posting id="3256" topic="AI:personalities:eliza"
created="261492300" notify="true" pre="true"
sandbox="jsp" stylesheeet="true" userId="brubble"
kbName="The Book of Zamples"
packageName="Live Code Examples for Fun and Profit"
className="My Fingers Will Never Leave My Wrist"
methodName="Hello, World!">
<cmd><![CDATA[Hello, Cruel World!]]></cmd>
<imports><![CDATA[]]></imports>
<ranges><![CDATA[]]></ranges>
<subject><![CDATA[Hello, goodbye!]]></subject>
<purpose><![CDATA[If only I had a brain]]></purpose>
<description><![CDATA[At least life on autopilot is stress-free!]]></description>
</Posting>
<Posting id="3146" created="261488000" notify="true" pre="true"
sandbox="jsp" stylesheet="true" userId="fflinstone">
kbName="The Book of Zamples"
packageName="Live Code Examples for Fun and Profit"
className="My Fingers Will Never Leave My Wrist"
methodName="Hello, World!"
<applet><![CDATA[]]></applet>
<cmd><![CDATA[Hello, World!]]></cmd>
<imports><![CDATA[]]></imports>
<ranges><![CDATA[]]></ranges>
<subject><![CDATA[Hello again!]]></subject>
<topic><![CDATA[oop:best practices]]></topic>
<purpose><![CDATA[If only I had a brain]]></purpose>
<description><![CDATA[At least life on autopilot is stress-free!]]></description>
</Posting>
</Postings>
Here is a similar query.
http://zamples.com/JspExplorer/zamples/kbSearch?count=2&clientUid=myUid&clientPassword=myPwd
For the sake of illustration,
let us assume that by extroadinary co-incidence, the first two records of this search
resulted in the same first two records as the previous search above.
Notice how few the attributes are present in the Postings element, because
the URL query only specified a count parameter.
As a result, the Posting elements have the maximum number of attributes
possible since the attributes will be reported in those elements instead of the
Postings element.
You can think of the Postings element as a header record,
and the Posting element as a detail record:
<?xml version="1.0"?>
<Postings start="1 count="2" matches="2">
<Posting id="1435" created="261492300" notify="true" pre="true"
sandbox="jsp" stylesheeet="true" userId="brubble"
kbName="The Book of Zamples"
packageName="Live Code Examples for Fun and Profit"
className="My Fingers Will Never Leave My Wrist"
methodName="Hello, World!">
<cmd><![CDATA[Hello, Cruel World!]]></cmd>
<imports><![CDATA[]]></imports>
<ranges><![CDATA[]]></ranges>
<subject><![CDATA[Hello, goodbye!]]></subject>
<purpose><![CDATA[If only I had a brain]]></purpose>
<description><![CDATA[At least life on autopilot is stress-free!]]></description>
</Posting>
<Posting id="3146" created="261488000" notify="true" pre="true"
sandbox="jsp" stylesheet="true" userId="fflinstone"
kbName="The Book of Zamples"
packageName="Live Code Examples for Fun and Profit"
className="My Fingers Will Never Leave My Wrist"
methodName="Hello, World!">
<applet><![CDATA[]]></applet>
<cmd><![CDATA[Hello, World!]]></cmd>
<imports><![CDATA[]]></imports>
<ranges><![CDATA[]]></ranges>
<subject><![CDATA[Hello again!]]></subject>
<purpose><![CDATA[If only I had a heart]]></purpose>
<description><![CDATA[Actually, I have a big heart!]]></description>
</Posting>
</Postings>
Possible error codes
In addition to the common error statuses, this Zamples REST call can
generate the following error statuses and messages:
| 404 Zamples knowledge base not found |
The requested knowledge base does not exist. |
| 508 Zamples search failed |
The search encountered an unspecified error |
| 
