You are viewing a plain text version of this content. The canonical link for it is here.
Posted to xap-commits@incubator.apache.org by bb...@apache.org on 2006/11/12 06:13:33 UTC
svn commit: r473886 - in /incubator/xap/trunk/src/xap: ./ application/
macro/ requestservice/ session/ util/ xml/ xml/dom/
Author: bbuffone
Date: Sat Nov 11 22:13:33 2006
New Revision: 473886
URL: http://svn.apache.org/viewvc?view=rev&rev=473886
Log:
Added documentation to the Public Classes.
Modified:
incubator/xap/trunk/src/xap/Xap.js
incubator/xap/trunk/src/xap/application/Application.js
incubator/xap/trunk/src/xap/macro/Macro.js
incubator/xap/trunk/src/xap/requestservice/HttpRequest.js
incubator/xap/trunk/src/xap/requestservice/NetServiceListener.js
incubator/xap/trunk/src/xap/requestservice/RequestService.js
incubator/xap/trunk/src/xap/session/ClientSession.js
incubator/xap/trunk/src/xap/util/LogFactory.js
incubator/xap/trunk/src/xap/xml/DocumentContainer.js
incubator/xap/trunk/src/xap/xml/dom/Document.js
incubator/xap/trunk/src/xap/xml/dom/XapElement.js
Modified: incubator/xap/trunk/src/xap/Xap.js
URL: http://svn.apache.org/viewvc/incubator/xap/trunk/src/xap/Xap.js?view=diff&rev=473886&r1=473885&r2=473886
==============================================================================
--- incubator/xap/trunk/src/xap/Xap.js (original)
+++ incubator/xap/trunk/src/xap/Xap.js Sat Nov 11 22:13:33 2006
@@ -15,6 +15,15 @@
*
*/
+/**
+ * @class
+ */
+
+/**
+ * Never use the constructor the Xap object is meant to be used through its list
+ * of static functions.
+ * @constructor
+ */
Xap = function(){}
/**
@@ -23,7 +32,23 @@
*/
/**
- * Static method to create an application.
+ * Static method to create an application. jkl jk
+ *<pre>
+ *<script language="JavaScript" type="text/javascript">
+ *var myApp = null;
+ *function launch() {
+ * myApp = Xap.createApplication(
+ * {
+ * configFilePath:"XapConfig.js"
+ * }
+ * );
+ *}
+ *</script>
+ *</head>
+ *<body onload="launch();">
+ *</pre>
+ * @return The xap.application.Application object created.
+ * @type xap.application.Application
*/
Xap.createApplication = function(applicationConfig) {
Xap.require("xap.application.Application");
@@ -35,7 +60,19 @@
}
/**
- * Static method to create applications objects for all the embedded applications.
+ * Static method to create applications objects for all the embedded applications. An embedded
+ * application is defined by any html object that contains the "startingPage" attribute. Once
+ * the "startingPage" object is detected, the creation process will look for the following
+ * attributes to be used to configure the application.
+ * <ul>
+ * <li>startingPage</li>
+ * <li>context</li>
+ * <li>applicationName</li>
+ * <li>configFilePath</li>
+ * </ul>
+ * @return window.xapApplications array object that contains all the applications created
+ * by scanniing the HTML document.
+ * @type Array
*/
Xap.createEmbeddedApplications = function() {
Xap.require("xap.html.HtmlConnector");
Modified: incubator/xap/trunk/src/xap/application/Application.js
URL: http://svn.apache.org/viewvc/incubator/xap/trunk/src/xap/application/Application.js?view=diff&rev=473886&r1=473885&r2=473886
==============================================================================
--- incubator/xap/trunk/src/xap/application/Application.js (original)
+++ incubator/xap/trunk/src/xap/application/Application.js Sat Nov 11 22:13:33 2006
@@ -14,36 +14,44 @@
* limitations under the License.
*
*/
+
Xap.provide("xap.application.Application");
Xap.require("xap.util.Exception");
Xap.require("xap.session.ClientSession");
Xap.require("xap.util.LogFactory");
/**
+ * @class
* xap.application.Application controls the creation of xap applications
* This class is a developer facing class to instaniation a XAP application
* with in a web page.
- * @author bbuffone
- */
-
-/**
- * Configuration object
*
+ * Configuration object
+ * <code>
* applicationConfig = {
* applicationName: "myApplication",
* startPage: "index.xal",
* context: "../../",
+ * configFilePath: "xap/config/XapConfig.js",
* toolkitType: "dojo",
* element: "MyApplicationRoot",
* scanPage: true,
* debug: false,
* };
- *
+ * </code>
+ *
+ * To obtain instances of an Application object store the return value from the Xap.createApplication()
+ * method or use the <code>window.xapApplications["MyApplicationName"].</code> Application names can be
+ * supplied as an embedded attribute or via the XapConfig.js file.
+ *
+ * @author bbuffone
*/
-//-----------------------------------------------------------------------
-// Constructors.
-//-----------------------------------------------------------------------
+/**
+ * @constructor
+ * @param applicationConfig Configuration object passed in will override any properties
+ * supplied in the XapConfig.js.
+ */
xap.application.Application = function(applicationConfig) {
if (applicationConfig != null){
this._applicationConfig = applicationConfig;
@@ -57,8 +65,9 @@
}
/**
- * The method creates the session and starts it. Also scans the page if the
- * user wants to.
+ * @private
+ * This method is responsible for starting the applicaiton. Depending on
+ * configuration information. Logging will be enabled.
*/
xap.application.Application.prototype.create = function() {
//load configuration information and merge the objects.
@@ -90,6 +99,8 @@
/**
* Get the session object for this application
+ * @return ClientSession object that was created during initialization.
+ * @type xap.session.ClientSession
*/
xap.application.Application.prototype.getSession = function() {
return this._session;
@@ -97,6 +108,8 @@
/**
* Get the configuration object that was used to start the application.
+ * @return The configuration object containing the loaded configuration
+ * file properties as will as the supplied properties to the constructor
*/
xap.application.Application.prototype.getConfiguration = function() {
return this._configuationObject;
@@ -104,6 +117,10 @@
/**
* Get the configuration object that was used to start the application.
+ * @argument eventString A string that contains the event to be fires. The string can
+ * contain all of the same events that are supplied to a component event handler.
+ * @return Any any information that is supplied be the
+ * EventHandler.fireEvent
*/
xap.application.Application.prototype.fireEvent = function(eventString) {
var clientEvent = new xap.session.ClientEvent(null, this.getSession());
@@ -115,6 +132,7 @@
// Private Methods.
//-----------------------------------------------------------------------
/**
+ * @private
* Method is used to create the configration and merge the objects.
*/
xap.application.Application.prototype._processConfiguration = function() {
Modified: incubator/xap/trunk/src/xap/macro/Macro.js
URL: http://svn.apache.org/viewvc/incubator/xap/trunk/src/xap/macro/Macro.js?view=diff&rev=473886&r1=473885&r2=473886
==============================================================================
--- incubator/xap/trunk/src/xap/macro/Macro.js (original)
+++ incubator/xap/trunk/src/xap/macro/Macro.js Sat Nov 11 22:13:33 2006
@@ -19,14 +19,6 @@
Xap.require("xap.xml.ParserFactory");
Xap.require("xap.util.MessageFormat");
-
-/**
- * @fileoverview A macro is a segment of stored xml that can be run from the client
- * as if it came from the server in a retrieveAndProcess()
- *
- * @author jmargaris
- */
-
/**
* Creates a new xap.macro.Macro instance.
@@ -37,6 +29,34 @@
* @class A macro is a segment of stored xml that can be run oncommand as if
* it came from the server. xap.macro.Macros should support arguments via something
* like java MessageFormat but these don't yet.
+ * A macro is a segment of stored xml that can be run from the client
+ * as if it came from the server in a retrieveAndProcess(). Macros are obtained by
+ * using the following process. <br><br>
+ *
+ * <code>
+ * <xap.application.Application>.getSession().getMacroContainer().getMacro("myMacro").execute();
+ * </code>
+ * <br><br>
+ * Macros can also be executed declaritively in component event handlers.<br><br>
+ * <code><button onCommand="macro:myMacro.execute()"/><br><br>
+ *
+ * <b>Defining a Macro</b><br>
+ *
+ *<pre>
+ * <macro:macro id="mymacro">
+ * <xm:modifications>
+ * <xm:append select="id('myPanel')">
+ * <xal:button text="{0}" y="60%"/>
+ * </xm:append>
+ * </xm:modifications>
+ * </macro:macro>
+ *</pre>
+ * <br><br>
+ * In the sample above the text="{0}" says that this macro will be parameterized. To
+ * change the value of the {0} pass in a value want into the execute("Hello") method.
+ *
+ * <br><br>
+ * @author jmargaris
*
*/
xap.macro.Macro = function( macroText, session ) {
@@ -51,6 +71,11 @@
//-----------------------------------------------------------------------
// Public Methods.
//-----------------------------------------------------------------------
+/**
+ * Method is used to create execute a macro. A variable list of parameters
+ * can be supplied to the execute method. The parameters will be used
+ * in the creation of the parameterized macro.
+ */
xap.macro.Macro.prototype.execute = function() {
var finalText = this._macroText;
Modified: incubator/xap/trunk/src/xap/requestservice/HttpRequest.js
URL: http://svn.apache.org/viewvc/incubator/xap/trunk/src/xap/requestservice/HttpRequest.js?view=diff&rev=473886&r1=473885&r2=473886
==============================================================================
--- incubator/xap/trunk/src/xap/requestservice/HttpRequest.js (original)
+++ incubator/xap/trunk/src/xap/requestservice/HttpRequest.js Sat Nov 11 22:13:33 2006
@@ -17,7 +17,17 @@
Xap.provide('xap.requestservice.HttpRequest');
-
+/**
+ * @class
+ * HttpRequest object is provide to the the RequestService to configure the
+ * HTTP request that is made.
+ */
+
+/**
+ * @constructor
+ * @param url The url that will be called when the request is executed.
+ * @method Method is either "POST" or "GET"
+ */
xap.requestservice.HttpRequest = function(url, method) {
this._url = url;
this._method = method || 'GET'; /* default is GET */
Modified: incubator/xap/trunk/src/xap/requestservice/NetServiceListener.js
URL: http://svn.apache.org/viewvc/incubator/xap/trunk/src/xap/requestservice/NetServiceListener.js?view=diff&rev=473886&r1=473885&r2=473886
==============================================================================
--- incubator/xap/trunk/src/xap/requestservice/NetServiceListener.js (original)
+++ incubator/xap/trunk/src/xap/requestservice/NetServiceListener.js Sat Nov 11 22:13:33 2006
@@ -19,14 +19,12 @@
-
- /**
+/**
+ * @class
* xap.requestservice.NetServiceListener is used as a callback for asynchronous
* NetService operations. The xap.requestservice.NetServiceListener is called back
* when an asynchronous call either completes successfully or fails
* due to an error.
- *
- * TODO rethink the API
*
* @author ikaplansky
*/
Modified: incubator/xap/trunk/src/xap/requestservice/RequestService.js
URL: http://svn.apache.org/viewvc/incubator/xap/trunk/src/xap/requestservice/RequestService.js?view=diff&rev=473886&r1=473885&r2=473886
==============================================================================
--- incubator/xap/trunk/src/xap/requestservice/RequestService.js (original)
+++ incubator/xap/trunk/src/xap/requestservice/RequestService.js Sat Nov 11 22:13:33 2006
@@ -15,23 +15,27 @@
*
*/
-/**
- * RequestService provides methods for sending and receiving
- * HTTP messages, and other request based functions.
- */
-
-
-
Xap.provide("xap.requestservice.RequestService");
-
Xap.require("xap.xml.ParserFactory") ;
Xap.require("xap.util.HttpUtils");
-//IMPORTANT make it clear you can use HttpRequest here, not just urls!
-//-----------------------------------------------------------------------
-// Constructors.
-//-----------------------------------------------------------------------
+/**
+ * @class
+ * RequestService provides methods for sending and receiving
+ * HTTP messages, and other request based functions.
+ *
+ * To obtain the RequestService use the following flow:
+ *
+ * <xap.application.Application<.getSession().getRequestService();
+ * <br><br>
+ */
+
+/**
+ * @contructor
+ * Never use the constructor, the RequestObject can be obtained
+ * from the ClientSession object.
+ */
xap.requestservice.RequestService = function( clientSession ) {
this._clientSession = clientSession;
}
@@ -63,6 +67,7 @@
}
/**
+ * @private
* Method used to get the first page of the application. This is special-cased
* as we may want to do something more advanced (like show/hide splash screen)
* in the future.
@@ -145,6 +150,7 @@
}
/**
+ * @private
* Parses the xml string into a Document and then walks the resulting Document
* dispatching elements to appropriate NamespaceHandlers.
*/
Modified: incubator/xap/trunk/src/xap/session/ClientSession.js
URL: http://svn.apache.org/viewvc/incubator/xap/trunk/src/xap/session/ClientSession.js?view=diff&rev=473886&r1=473885&r2=473886
==============================================================================
--- incubator/xap/trunk/src/xap/session/ClientSession.js (original)
+++ incubator/xap/trunk/src/xap/session/ClientSession.js Sat Nov 11 22:13:33 2006
@@ -214,6 +214,9 @@
//-----------------------------------------------------------------------
// Private Methods.
//-----------------------------------------------------------------------
+/**
+ * @private
+ */
xap.session.ClientSession.prototype._start = function( appConfigObject ) {
//enable logging if needed.
if(appConfigObject.loggingEnabled != null) {
@@ -249,6 +252,9 @@
}
+/**
+ * @private
+ */
xap.session.ClientSession.prototype._processPluginConfigurationFiles = function (pluginFiles){
var requestService = this.getRequestService();
for( var i = 0; i < pluginFiles.length; i++ ) {
@@ -258,6 +264,9 @@
}
}
+/**
+ * @private
+ */
xap.session.ClientSession.prototype._processPluginConfigurationClasses = function (pluginClasses){
for( var i = 0; i < pluginClasses.length; i++ ) {
var className = pluginClasses[ i ];
@@ -266,6 +275,7 @@
}
/**
+ * @private
* This function creates the intitial xml document for the session.
* This function is only called if there is a starting page.
*/
Modified: incubator/xap/trunk/src/xap/util/LogFactory.js
URL: http://svn.apache.org/viewvc/incubator/xap/trunk/src/xap/util/LogFactory.js?view=diff&rev=473886&r1=473885&r2=473886
==============================================================================
--- incubator/xap/trunk/src/xap/util/LogFactory.js (original)
+++ incubator/xap/trunk/src/xap/util/LogFactory.js Sat Nov 11 22:13:33 2006
@@ -15,20 +15,25 @@
*
*/
-//Let Dojo know what to expect from this file:
Xap.provide("xap.util.LogFactory");
Xap.provide("xap.util.LogFactory.ConsoleLog");
- /**
- * @constructor
- * TODO either replace or expand this to work with some other logging
- * framework
- *
- * xap.util.LogFactory provides a single static method that may be used to retrieve
+
+/**
+ * @class xap.util.LogFactory provides a single static method that may be used to retrieve
* a named Log interface. Multiple calls to the <code>getLog()</code> method
* with the same argument will return the same instance of the Log.
*
+ * <b>To turn the logging on</b> set the "logging" property to the true
+ * in the XapConfig.js
+ *
* @author ikaplansky
*/
+
+/**
+ * @constructor
+ * TODO either replace or expand this to work with some other logging
+ * framework
+ */
xap.util.LogFactory = function(){} ;
//-----------------------------------------------------------------------
@@ -46,9 +51,6 @@
//-----------------------------------------------------------------------
-
-
-
/**
* Returns an instance of Log for use in logging.
* Bypasses an IE Object problem by replacing all
@@ -75,14 +77,17 @@
//-----------------------------------------------------------------------
-
+/**
+ * @class ConsoleLog allows developers to write debugging information
+ * to the console. Use the methods provided to log different types of information.
+ */
xap.util.LogFactory.ConsoleLog = function( name ) {
this._name = name;
this._isDebug = true;
}
xap.util.LogFactory.ConsoleLog.s_logWindow = null;
-
+
xap.util.LogFactory.ConsoleLog.prototype.isDebug = function() {
return this._isDebug;
}
Modified: incubator/xap/trunk/src/xap/xml/DocumentContainer.js
URL: http://svn.apache.org/viewvc/incubator/xap/trunk/src/xap/xml/DocumentContainer.js?view=diff&rev=473886&r1=473885&r2=473886
==============================================================================
--- incubator/xap/trunk/src/xap/xml/DocumentContainer.js (original)
+++ incubator/xap/trunk/src/xap/xml/DocumentContainer.js Sat Nov 11 22:13:33 2006
@@ -34,7 +34,9 @@
* @class xap.xml.DocumentContainer is a version of xap.session.Container that holds
* xml documents. It extends the normal xap.session.Container by adding
* the <code>getUiDocument</code> method that returns the starting
- * UI document that exists at startup for all applications.
+ * UI document that exists at startup for all applications.<br><br>
+ * To gain access to the DocumentContainer use the following flow.<br><br>
+ * <xap.application.Application>.getSession().getDocumentContainer()<br><br>
*
* @see xap.session.Container
* @constructor
Modified: incubator/xap/trunk/src/xap/xml/dom/Document.js
URL: http://svn.apache.org/viewvc/incubator/xap/trunk/src/xap/xml/dom/Document.js?view=diff&rev=473886&r1=473885&r2=473886
==============================================================================
--- incubator/xap/trunk/src/xap/xml/dom/Document.js (original)
+++ incubator/xap/trunk/src/xap/xml/dom/Document.js Sat Nov 11 22:13:33 2006
@@ -26,7 +26,8 @@
Xap.require("xap.util.ArrayHelper");
/**
- * @fileoverview The xap.xml.dom.Document object represents an entire XML document.
+ * @fileoverview
+ * The xap.xml.dom.Document object represents an entire XML document.
* Conceptually, it is the root of the document tree, and provides the
* primary access to the document's data.
*
Modified: incubator/xap/trunk/src/xap/xml/dom/XapElement.js
URL: http://svn.apache.org/viewvc/incubator/xap/trunk/src/xap/xml/dom/XapElement.js?view=diff&rev=473886&r1=473885&r2=473886
==============================================================================
--- incubator/xap/trunk/src/xap/xml/dom/XapElement.js (original)
+++ incubator/xap/trunk/src/xap/xml/dom/XapElement.js Sat Nov 11 22:13:33 2006
@@ -966,6 +966,9 @@
}
+/**
+ * @private
+ */
xap.xml.dom.XapElement.prototype._fireStructureChangeEvent = function( doc, event, methodName){
if (doc){
this._notifyListeners(doc._structureChangeListeners,
@@ -976,6 +979,9 @@
}
+/**
+ * @private
+ */
xap.xml.dom.XapElement.prototype._fireAttributeChangeEvent = function( doc, event, methodName){
if (doc){
this._notifyListeners(doc._attributeChangeListeners,
@@ -1014,7 +1020,9 @@
-/** @private */
+/**
+ * @private
+ */
xap.xml.dom.XapElement.prototype._doAnyAttributeChangeListenersExist = function( doc ) {
var normalListeners = null;
if ( doc != null ) {
@@ -1102,8 +1110,9 @@
//-----------------------------------------------------------------------
-
-/** @private */
+/**
+ * @private
+ */
xap.xml.dom.XapElement.prototype._cloneHelper = function( deep, withIds, parser ) {
var e = new xap.xml.dom.XapElement( this.nodeName );
@@ -1163,7 +1172,9 @@
}
-/** @private */
+/**
+ * @private
+ */
xap.xml.dom.XapElement.prototype._encodeEverythingButSingleTicks = function( s ) {
if ( s == null ) { return ""; }
var buffer = new Array( s.length );