Opinion What Is a Web App?

Here s Our Definition Jarel Remick on January 30th 2011 definition, Flash, HTML5, web app, webappDo you know what a web app is? Do you k now what s used to make it? Covering web apps on Web.AppStorm isn t quite as straigh t forward as you might think. There are many different technologies that are use d to create web apps of many different types. Flash, JavaScript, HTML5, PHP, Jav a, Silverlight, web services vs dedicated applications what qualifies as a web ap p and what doesn t? I occasionally receive comments stating that certain web apps aren t actually web apps, when indeed they are. So, I would like to take a moment to clear things up and give you our take on what a web app really is. Web App: Our Simple Definition Though fully describing what a web app (application) is can be lengthy, ours des cription is quite simple. A web application is an application utilizing web and [web] browser technologies to accomplish one or more tasks over a network, typically through a [web] brows er. Let s Break It Down Application [Software]: Application software, also known as an application or an a pp , is computer software designed to help the user to perform singular or multipl e related specific tasks. View on Wikipedia Web technologies: Flash, Silverlight, JavaScript, HTML & CSS, Java, various othe r programming languages and other computer technology intended for the use acros s networks. Network: The internet or intranet. see Wikipedia description Browser: Firefox, Chrome, Safari, Opera, Internet Explorer and various others. s ee

Web Applications: What are they? What of them? Web Applications or Website Widgets Over the past decade or so, the web has been embraced by millions of businesses as an inexpensive channel to communicate and exchange information with prospects and transactions with customers. In particular, the web provides a way for marketers to get to know the people vi siting their sites and start communicating with them. One way of doing this is a sking web visitors to subscribe to newsletters, to submit an application form wh en requesting information on products or provide details to customize their brow sing experience when next visiting a particular website. The web is also an excellent sales channel for a myriad of organizations, large or small: with over 1 billion Internet users today (source: Computer Industry Al manac, 2006), US e-commerce spending accounted for $102.1 billion in 2006 (Sourc e: comScore Networks, 2007). All this data must be somehow captured, stored, processed and transmitted to be used immediately or at a later date. Web applications, in the form of submit fie lds, enquiry and login forms, shopping carts, and content management systems, ar e those website widgets that allow this to happen.

They are, therefore, fundamental to businesses for leveraging their online prese nce thus creating long-lasting and profitable relationships with prospects and c ustomers. No wonder web applications have become such a ubiquitous phenomenon. However, du e to their highly technical and complex nature, web applications are a widely un known and a grossly misunderstood fixture in our everyday cyber-life. Web applications defined From a technical view-point, the web is a highly programmable environment that a llows mass customization through the immediate deployment of a large and diverse range of applications, to millions of global users. Two important components of a modern website are flexible web browsers and web applications; both available to all and sundry at no expense. Web browsers are software applications that allow users to retrieve data and int eract with content located on web pages within a website. Today s websites are a far cry from the static text and graphics showcases of the early and mid-nineties: modern web pages allow personalized dynamic content to b e pulled down by users according to individual preferences and settings. Further more, web pages may also run client-side scripts that change the Internet browser into an interface for such applications as web mail and interactive mapping soft ware (e.g., Yahoo Mail and Google Maps). Most importantly, modern web sites allow the capture, processing, storage and tr ansmission of sensitive customer data (e.g., personal details, credit card numbe rs, social security information, etc.) for immediate and recurrent use. And, thi s is done through web applications. Such features as webmail, login pages, suppo rt and product request forms, shopping carts and content management systems, sha pe modern websites and provide businesses with the means necessary to communicat e with prospects and customers. These are all common examples of web application s. Web applications are, therefore, computer programs allowing website visitors to submit and retrieve data to/from a database over the Internet using their prefer red web browser. The data is then presented to the user within their browser as information is generated dynamically (in a specific format, e.g. in HTML using C SS) by the web application through a web server. For the more technically oriented, Web applications query the content server (es sentially a content repository database) and dynamically generate web documents to serve to the client (people surfing the website). The documents are generated in a standard format to allow support by all browsers (e.g., HTML or XHTML). Ja vaScript is one form of client side script that permits dynamic elements on each page (e.g., an image changes once the user hovers over it with a mouse). The we b browser is key - it interprets and runs all scripts etc. while displaying the requested pages and content. Wikipedia brilliantly terms the web browser as the u niversal client for any web application . Another significant advantage of building and maintaining web applications is th at they perform their function irrespective of the operating system and browsers running client side. Web applications are quickly deployed anywhere at no cost and without any installation requirements (almost) at the user s end. As the number of businesses embracing the benefits of doing business over the we b increases, so will the use of web applications and other related technologies continue to grow. Moreover, since the increasing adoption of intranets and extra nets, web applications become greatly entrenched in any organization s communicati on infrastructures, further broadening their scope and possibility of technologi

cal complexity and prowess. Web applications may either be purchased off-the-shelf or created in-house. How do web applications work? The figure below details the three-layered web application model. The first laye r is normally a web browser or the user interface; the second layer is the dynam ic content generation technology tool such as Java servlets (JSP) or Active Serv er Pages (ASP), and the third layer is the database containing content (e.g., ne ws) and customer data (e.g., usernames and passwords, social security numbers an d credit card details).

The figure below shows how the initial request is triggered by the user through the browser over the Internet to the web application server. The web application accesses the databases servers to perform the requested task updating and retri eving the information lying within the database. The web application then presen ts the information to the user through the browser.

Web Security Issues Despite their advantages, web applications do raise a number of security concern s stemming from improper coding. Serious weaknesses or vulnerabilities, allow ha ckers to gain direct and public access to databases in order to churn sensitive data. Many of these databases contain valuable information (e.g., personal and f inancial details) making them a frequent target of hackers. Although such acts o f vandalism as defacing corporate websites are still commonplace, nowadays, hack ers prefer gaining access to the sensitive data residing on the database server because of the immense pay-offs in selling the data. In the framework described above, it is easy to see how a hacker can quickly acc ess the data residing on the database through a dose of creativity and, with luc k, negligence or human error, leading to vulnerabilities in the web applications . As stated, websites depend on databases to deliver the required information to v isitors. If web applications are not secure, i.e., vulnerable to, at least one o f the various forms of hacking techniques, then your entire database of sensitiv e information is at serious risk. Some hackers, for example, may maliciously inject code within vulnerable web app lications to trick users and redirect them towards phishing sites. This techniqu e is called Cross-Site Scripting and may be used even though the web servers and database engine contain no vulnerability themselves. Recent research shows that 75% of cyber attacks are done at web application leve l.

Websites and related web applications must be available 24 hours a day, 7 days a week, to provide the required service to customers, employees, suppliers and ot her stakeholders. Firewalls and SSL provide no protection against web application hacking, simply because access to the website has to be made public All modern database systems (e.g. Microsoft SQL Server, Oracle and MySQL) may be accessed through specific p orts (e.g., port 80 and 443) and anyone can attempt direct connections to the da tabases effectively bypassing the security mechanisms used by the operating syst

em. These ports remain open to allow communication with legitimate traffic and t herefore constitute a major vulnerability. Web applications often have direct access to backend data such as customer datab ases and, hence, control valuable data and are much more difficult to secure. Th ose that do not have access will have some form of script that allows data captu re and transmission. If a hacker becomes aware of weaknesses in such a script, h e may easily reroute unwitting traffic to another location and illegitimately hi ve off personal details. Most web applications are custom-made and, therefore, involve a lesser degree of testing than off-the-shelf software. Consequently, custom applications are more susceptible to attack Web applications, therefore, are a gateway to databases especially custom applic ations which are not developed with security best practices and which do not und ergo regular security audits. In general, you need to answer the question: Which parts of a website we thought are secure are open to hack attacks? and what data c an we throw at an application to cause it to perform something it shouldn t do? . This is the work of a web vulnerability scanner. Acunetix Web Vulnerability Scanner Proof of such exploits are readily available on the Internet and are the subject of discussion in several press releases by Acunetix, a leading vendor of web ap plication security products. Click here to learn more about Acunetix Web Vulnera bility Scanner. Scanning for XSS vulnerabilities with Acunetix WVS Free Edition To check whether your website has cross site scripting vulnerabilities, download the Free Edition from http://www.acunetix.com/cross-site-scripting/scanner.htm. This version will scan any website / web application for XSS vulnerabilities an d it will also reveal all the essential information related to it, such as the v ulnerability location and remediation techniques. Scanning for XSS is normally a quick exercise (depending on the size of the web-site). Articles on Web Security Exploiting a cross-site scripting vulnerability on Facebook CRLF Injection attacks and HTTP Response Splitting Apache Web Server Security IIS Web Server Security Web Server Security and Database Server Security More Articles White Papers on Web Security A complete guide to securing a website Why File Upload Forms are a major security threat Finding the right web application scanner; why black box scanning is not enough The Payment Card Industry Compliance - Securing both Merchant and Customer data. Web Services - The Technology and its Security Concerns More White Papers

Abbreviation of application program interface, a set of routines, protocols, and tools for building software applications. A good API makes it easier to develop a program by providing all the building blocks. A programmer then puts the bloc ks together. Most operating environments, such as MS-Windows, provide an API so that programm ers can write applications consistent with the operating environment. Although A PIs are designed for programmers, they are ultimately good for users because the y guarantee that all programs using a common API will have similar interfaces. T his makes it easier for users to learn new programs.

Abbreviation of application program interface, a set of routines, protocols, and tools for building software applications. A good API makes it easier to develop a program by providing all the building blocks. A programmer then puts the bloc ks together. Most operating environments, such as MS-Windows, provide an API so that programm ers can write applications consistent with the operating environment. Although A PIs are designed for programmers, they are ultimately good for users because the y guarantee that all programs using a common API will have similar interfaces. T his makes it easier for users to learn new programs.

defination of API hello, API stands for Application Program Interface. Basically, one Internet applicatio n can exchange information with another application via an API. When a software application is built, coders and SEO project managers will decide which API stan dards to adhere to. Application Program Interface standards include software bui lding tools, protocols, and standardized routines.

Definition application program interface (API) E-mail Print A AA AAA LinkedIn Facebook Twitter Share ThisRSS Reprints An application program interface (API - and sometimes spelled application progra mming interface) is the specific method prescribed by a computer operating syste m or by an application program by which a programmer writing an application prog ram can make requests of the operating system or another application. An API can be contrasted with a graphical user interface or a command interface (both of which are direct user interfaces) as interfaces to an operating system or a program.

What is an API? Your guide to the Internet Business (R)evolutionPosted on March 11, 2011 by MarkCheshire -------------------------------------------------------------------------------New, FREE whitepaper available for immediate download!

Bridge the API education gap between the technology and business teams Many API initiatives start as a technology driven project. Most of these projec ts also need the endorsement or sponsorship of the business team in order to rea lize the full potential and to gain approval for the the appropriate investments . It is frequently a struggle to explain to the business team in a clear and co mpelling way why APIs are important to your business. At 3scale we have helped many customers with the task of bridging this education gap. We have also seen great variety of approaches that work well.

Benefits for a business and technical audience We are now making a whitepaper resource available to you to accelerate this task , and to benefit from our experience. The whitepaper is aimed at an audience of business executives and entrepreneurs who understand basic computing concepts, but do not have an engineering background. This will also be useful to CTO s and others in the technical team, who would like to learn other approaches to evange lize the need for an API. The whitepaper explains the basic definition of an API . It describes the dramatic changes in the way in which APIs have evolved some would say it is a revolution. By way of analogy with the car industry and how i ndustries scale up, we highlight the broader potential to completely reshape the way we do business on the Internet. We conclude with a peek at the future on h ow APIs will continue to grow in impact.

usage ofapi Feb 2, 2006 3:10 AM Usage of APIBased on the eval version 1.1.1 I tried to use the CPUProfiler API m ethods for profiling specific pieces of my code. To this end, I inserted CPUProfiler.Start() and CPUProfiler.StopAndSaveSnapshot() statements and compiled my.exe successfully (copy local true for JetBrains.dottrace.Api.dll). How do I use my.exe together with the profiler? Will the StopAndSaveSnapshot method pop up the dottrace profiler application? Or will a run of the

dottrace profiler on my.exe take the API statements into acount? In both cases I was not able to display any generated snapshot.

Deducing an Applications use of API's Derek Jones derek@knosof.co.uk Knowledge Software Ltd Farnborough, Hants UK Introduction API's (Application Program Interface) have become the method by which vendors de fine the software interface to their products. The product could be a piece of h ardware, a third party library or even an operating system. Users of applications often need to know which API's an application relies on (f or instance when purchasing hardware and software separately). Managers of devel opment teams would probably like to know that only the defined API is being used and that the interface rules laid down in the specification are being followed (to reduce the likelyhood of their product becoming tied to a particular version , or vendors implementation of an API). To date, those people not intimately familiar with the source code of the applic ation have had no way of finding out what APIs are being used and if the defined API is being followed. Now a new option has been added to OSPC (Open Systems Portability Checker). The -api option. Switching this option on, prior to processing the source of an appl ication, will produce a listing of the API's used by the application and a summa ry of API specification violations. This article discusses the issues involved in checking API usage and the type of information produced for users to examine. We adopt the conventions used in the C language. What might an API define? Information can be passed through an interface via function calls or external va riables. To hide implementation details symbolic names (macros) are often used t o represent special numeric values and structures are used to hold a collection of variables in one object. The names of these functions, objects, macros and types are defined in one or mo re header files, to be included within the developers source code. To be of use the API must define more than the C syntax. It must define the prop erties of these names. For instance the external xyz represents a status flag an d can have any of the values given by the macros A, B or C. Which API's are used? An API checker has to do two things to answer this question.

It needs to scan the applications source looking for all uses of external identi fiers. It needs a database of API's and the identifiers they define, against which iden tifiers used in an application can be matched. All references to identifiers are matched against the contents of the API databa se, or other parts of the application (one unit may refer to an identifier defin ed in another unit, not an API). A match against an identifier contained in an A PI flags that API as being used (cases where different API's define the same ide ntifier are rare and can usually be resolved by looking at the context, ie inclu ded headers and the use made of the identifier). Identifiers that are not contained in another unit of the application or the API database are regarded as referring to an unknown API (they could equally be ref erring to vendor extensions or a particular API). Optional components An API is sometimes broken down into core and optional components. For instance the real time portion of POSIX has 16 optional components. The availability of t hese components can be tested for using feature test macros within the applicati on source code. To be useful, any report of API usage has to list those optional components of a n API that are used by the application. Are the interface conventions obeyed? It is no good making use of the facilities provided by an API if the interface c onventions are not followed. The whole purpose of an API is to isolate implement ation details from the application. An applications that does not follow the spe cified interface rules is likely to have problems when using a new version of a library implementing the API, or the application is moved to a different platfor m. So as well as finding out which identifiers are used, it is also necessary to ch eck that they are used correctly. Interface requirements specified in APIs API's specify a number of different requirements for correct usage. Commonly see n requirements include: Parameters Symbolic values must be used as arguments Types of arguments must be compatible with a defined type Function return values Value has a properties, ie is positive, is negative Value may only be compared against symbolic values Feature test macros Used to check availability of optional constructs Variable types Fields available in structs No requirement on layout of fields No requirement that the type be scalar Not always constant Macros need not evaluate to a compile time constant Headers Must be included Function calls An API function may accept input arguments, return a result or set status flags (for instance errno). Functions that may perform various operations usually take an argument specifyin g which operation to be perform. For instance in:

fseek(file_ptr, 4, SEEK_CUR); the third argument tells fseek that the seek is to be performed relative to the current file position. SEEK_CUR is a macro whose value will chosen by each imple mentation. The call: fseek(file_ptr, 4, 1); relies on an implementation choosing a SEEK_CUR value of 1. As such it does not obey the API specification, even though it will work on one or more implementati ons. Some API's have more complicated requirements. For instance the POSIX function o pen may take one of three values (O_RDONLY, O_WRONY, O_RDWR) combined with zero or more other values (O_APPEND, O_NONBLOCK, O_NOCTTY, O_TRUNC, O_CREAT, O_EXCL). An API checker must ensure that the argument is created using the correct boole an or of these macros. Checking a variable that is passed as an argument is substantially more difficul t. It requires full flow analysis to track the symbols assigned to that variable . The current release of OSPC does not perform such analysis in this context. APIs also define the types of the function parameters. Provided the host compile r supports function prototypes then the arguments given in calls to API function s will be checked at compile time. It is ok to pass an argument of a different a rithmetic type because the compiler will automatically insert a cast to the requ ired type. For instance if size_t has a unsigned long type, passing an int argum ent will work because of the implicit cast inserted by the compiler. Thus the de veloper does not have to worry about inserting casts to size_t for all appropria te arguments. Passing an incorrect non-arithmetic type will cause the compiler to generate a c ompile time error. It is useful for an API checking tool to check that the argum ents are compatible with the declared parameters, but not essential. Some company coding standards require that arguments passed to functions are `st rongly compatible' with the argument type. That is the named types must matched. But this is a coding standards requirement, not an API requirement (because of the implicit casts inserted by the compiler). API functions may also return values. These values may represent individual quan tities or particular properties, such as positiveness. For instance printf retur ns the number of characters printed or a negative value if an error occurred. if (printf("abc") == 3) /* OK */ ; if (printf("xyz") == -1) ; The first example is checking the number of characters written against the expec ted value, as allowed by the API. The second is assuming a particular value for the property of negativeness. One implementation may return -1, another -2, anot her an arbitrary negative value. The correct test would be: if (printf("xyz") < 0) ; here the relational operator is testing for the negative property. A grey area of checking involves functions that return a limited range of values . For instance the tm_sec field of a struct tm may take on values between 0 and 61. Is the following code fragment relying on an implementation defined extensio n or is it a coding bug?

if (t.tm_sec > 61) ; OSPC assumes that it is a coding problem and does not flag this code as not conf orming to the API. Like arguments, return values may sometimes be symbolic. if (fflush(file_ptr) == EOF) /* OK */ ; if (fflush(file_ptr) == 1) ; The second example is incorrect because it assumes a value for the symbol EOF. Also relational operators may not be used in those cases where all the values re turned by an API function are symbolic. Status flags Status flags set by API calls are usually there to provide additional informatio n. For instance errno might be set to some symbolic value to indicate the type o f a particular failure. Few API's require status flags to be checked by the appl ication. OSPC has the ability to detect that applications are checking status flags after an API call. However, it makes the assumption that such checking must occur in the first conditional statement after the API function call. This issue is regar ded as a coding standard issue, not an API specification requirement. Use of objects defined in API's Like function return values, objects often have limits placed on the values they may contained. errno is an example of such an object. It may be reset to zero b y the application, or it may be tested (using an equality operator) against a va riety of symbolic names. Optional constructs Use of an optional API construct must be protected by a feature test macro. For instance POSIX specifies that the function setuid is only available if the featu re test macro _POSIX_SAVED_IDS is defined. The developer thus has to write the c ode: #ifdef _POSIX_JOB_CONTROL setuid(23); #else do_something_else(23); #endif here the code is checking for the availability of setuid and taking alternative action if it is not available. Optional constructs may be any identifier declared or defined by the API. Developers that are unaware they are using optional constructs have set a future trap in the porting of their application. Users of packages also need to be awa re of any optional constructs required by an applications when specifying hardwa re or third party libraries. Use of headers Headers are the means by which identifiers defined by in API may be made visible to the application. In some cases the header must be included because it contai ns information that cannot be obtained elsewhere (for instance the values choose n by the implementation for symbolic names). Sometimes it is possible for a deve loper to declare a subset of the API without including the header. Headers are necessary if symbolic macros and types are referenced from the appli

cation source. For instance in the example involving fseek above the header stdi o.h needs to be included so that the compiler can obtained the value of the macr o SEEK_SET choosen by the implementation. An example where it is ok to declare a function explicitly, rather than includin g the header string.h, is the strerror function. Because its API specification o nly uses C predefined types, char *strerror(int errnum). However, memset could n ot be so declared in the users source without including the string.h header (if the header is included why explicitly declare it anyway). This is because the de claration of memset needs a type from that header, size_t. The developer may dec lare memset with a particular predefined type instead of size_t, but that will o nly work on implementations where that type is used to represent size_t. (The C API specifies the type void *memset(void *s, int c, size_t n)). Incorrect header contents A problem that sometimes arises with API headers is that they do not accurately reflect the requirements contained in an API. Fortunately the most common proble m, incorrectly specified parameter arithmetic types, does not affect the perform ance of a checking tool. If, for instance, a vendors version of string.h declare d the third parameter of memset to take an unsigned int argument the interface i s not broken from the applications point of view, provided size_t is also declar ed to have type unsigned int. The compiler vendor is at fault for not upgrading its headers to conform to the C standard (first published in 1989 by ANSI and as an ISO standard in 1992). Other problems often seen include syntax violations (text after a #endif not inc luded within comment delimiters for example) and incorrect numeric value for mac ros (floating point values inaccurate in the last digit). Use of API An API may t hardware variables defined types define types to allow implementations to adapt themselves to differen (usually different sized scalar types) or to combine together similar in one place (a struct).

APIs rarely define the ordering of fields within a struct, although implementati ons are usually given liberty to add additional fields to structs. Applications that rely on ordering of fields or make use of implementation specific fields ar e going beyond the specification given in the API. struct fields Initialisation of struct objects, via an initialiser, is one example where an or dering of fields is implied. So the construct: div_t local_var = {1, 2}; must be explicitly expanded out to (assuming the above assumed this order): div_t local_var; local_var.quot=1; local_var.rem=2; An example of an implementation adding additional fields to a structure is struc t dirent. On a Sun platform the code fragment: if (dirent_obj.d_reclen == 3) ; would happily compile. Other platforms are likely to complain that the field d_r eclen does not exist (it is not in the POSIX or XPG API's). Type need not be scalar An API occasionally leaves the specification of a particular type wide open. An example is the fpos_t typedef specified in the C standard, which simply states "

... which is an object type capable of recording all the information needed to s pecify uniquely every position within a file." On many systems this type is a sc alar. So the code: if (fp_1 == fp2) /* two variables of type fpos_t */ ; works. But C does not allow the == operator to be applied to struct types. This code fragment would fail to compile on a platform that defined fpos_t to be a st ruct (in fact there is no portable way of comparing two objects of arbitrary typ e for equality). Symbolic name need not be constant API's use symbolic macro names to represent values that may vary between impleme ntations. Developers sometimes assume that because macros are used the value wil l be a constant literal. This is sometimes not the case. For instance, of all th e macros used to describe properties of the floating point representation, in th e C standard, only one, FLT_RADIX, is required to be a constant expression. On m any implementation the other macros are indeed constant expressions, but they ar e not required to be. The code fragment: #include <float.h> int number[FLT_DIG]; relies on FLT_DIG, the number of decimal digits in a number that can be exactly represented in a float, being a constant expression. If it is an expression that must be evaluated, as above, at runtime the compiler will not be able to compil e the application. Implementation specific and future problems API's often reserve specific names for future releases of their specification. T hey also allow implementations to add additional names to headers, provided thos e names obey a few restrictions. The presence of these reserved names effectively constrains an application from defining identifiers with those names. An application containing such a definiti on could fail to compile on certain platforms, or with later versions of the API (because of duplicate or inconsistent definitions). Some reserved names are easy to avoid by the application developer, for instance those starting with double underscore. Others might be considered more contenti ous. For instance all macros starting with E (capital E) are reserved by the C s tandard if the header errno.h is included, and all external identifiers starting with the three characters str are reserved in all cases by the C standard. Experience has shown that applications often contain definitions of many identif iers whose names clash with those reserved by API's. The definitions could be ch anged to use alternative names, but in many cases the effort involved is disprop ortional to the time and effort needed to modify existing code. Insisting that all names defined by an application not clash with those reserved by the API's used is impractical. Instead an API checking tool should list all definitions that do clash, along with a count of the number of references to the m. Applications vendors might also undertake not to add new definitions to this existing list. Identifiers specified to have properties The C standard defines errno to "... expands to a modifiable lvalue that has typ e int ... It is unspecified whether errno is a macro or an identifier declared w ith external linkage." This is an example of an API defining properties of an in terface rather than C syntax for its implementation. The POSIX standard says ".. . which is defined as extern int errno;" An implementation specification.

This kind of API object specification, using properties rather than C syntax is not very common. Ideally an API checking tool would know about the different properties defined b y an API and flag discrepancies. From the tools point of view such special cases are just that, special cases. In the example above it was reasoned that few app lications rely solely on the C standard, most also include POSIX (or an API base d on POSIX). So checks suggested by the specification given in the C standard ar e not carried out by OSPC Use of identifiers of unknown status Once the entire application has been processed all referenced identifiers are kn own. Resolving these identifiers against those defined by the application and th ose defined by the known API's may leave some unaccounted for. These unaccounted identifiers are assumed to belong to either an unknown API or extensions to a known API. In the case of variables and macros there will be a declaration in one of the in cluded headers. The name of the header may give clues to the status of the ident ifier. Functions need not be declared prior to use. In this case the compiler will crea te a default declaration of extern int f(), where f is replaces by the name of t he function. So there may not be a header name to refer to for guidance. Once ag ain incorrectly written headers can confuse the analysis. It is not unknown for vendors to supply headers with some function declarations missing, even though c ode implementing that function is available in a library that can be linked agai nst. A checking tool can do no more than list identifiers whose status is unknown. Th is list may contain hints as to their likely status, for instance by giving the name of the header in which any declaration occurred. Identifier specified by several API's Sometimes a newer API will add functionality to an interface defined by an earli er API, or define what was previously undefined behaviour. For instance the C st andard says that the rename function may be used to change the name of a file. B ut C has no concept of directory structure, so it does not include any specifica tion for handling directories, it assumes a flat file system. POSIX defines a di rectory structure and adds to the specification to rename to describe how direct ories are to be handled. It is not always possible to deduce the use being made of an API interface from static analysis of the source. OSPC takes the view that if an identifier from an API is referenced then that API is used, irrespective of the number of API's in volved. Can all referenced API's be detected? No, they cannot. Consider the case of an API that only defines macros and types. Let us assume that information on this API is not available to OSPC. Who is to say that the included header, used to access the defined names, is not part of t he application, rather than an API? An example of of a header that only contains macros and typedefs is stddef.h, from the C standard. In the case of objects and functions their definition is contained in a library, not in the source making up an application. Such a library has the opportunity to modify an object and functions may access host specific information. Does it matter that use of an API may go undetected? Perhaps not. The developer has the option of taking the headers containing the macro and type definitions a nd making them part of the application source tree (if they are not available on a given platform). Of course the developer then has to take over responsibility

for ensuring that the definitions are correct for each new platform. In the ideal case the OSPC database contains information on an API's that an app lication uses. Information output by an API checking tool End users need a list of the API's used, along with a summary of any discrepanci es. Software developers would probably like any discrepancies to be pin pointed, simplifying the job of isolating and fixing them. Being able to output a list of applicable API's relies on having a database of i nformation about what each API contains. This is turn requires an API to be docu mented, which, unfortunately is not always the case (X11 being an example, where even the headers provided can vary between platforms, let alone the header cont ents). An API database takes time to build. Effort is also required to maintain it. The best approach to maintaining an API database is to make it easy for software ve ndors to create and maintain information on their own APIs, for distribution to customers. API descriptions contained in standards documents such as C and POSIX being provided by the company supplying the checking tools. Information summary API's used Optional components used Violations of the defined interface Type of violation and number of occurrences Reserved ids used API that reserves them Identifier name and number of references to it Identifiers referenced that are not in a known API included header functions external identifiers macros

how to create an api Behind almost every successful web application, there is an easy-to-use & featur e-rich API as they simply help the main application to spread into others & reac hed by more users. Also, an API-enabled application can be easily developed further using the API i tself. In order to create an API for your web application, here are 10 tutorials to get you started. But before that, you may want to checkout the video: KDE responds to critiqueSemantic Web Video tutorial How to create a good API By stefon O Reilly hosts an article presenting best practices for APIs API design goals What should the design goals of your API be? Apart from compatibility, the follo

wing goals from Elliotte s presentation seem like an excellent set: It must be absolutely correct. In the case of XOM, this meant that the API could never produce malformed XML documents no matter what the caller did. For the JM X API, for example, it means that you can never get the MBean Server into an inc onsistent state by registering strange MBeans in it or using funny ObjectNames o r performing several operations concurrently.

how to develop a web application How to develop Web Applications Introduction Apache Cocoon is an XML publishing framework. It allows you to define XML docume nts and transformations to be applied on it, to eventually generate a presentati on format of your choice (HTML, PDF, SVG, etc.). Cocoon also gives you the possi bility to have logic in your XML files (so that the XML file itself can become d ynamically generated). Cocoon is developed on top of the Avalon Server Framework, which is a stable and scalable framework. You can find out more about Avalon in this document: (ref: Avalon White Paper). I highly suggest reading this white paper as it covers many concepts that are key to Cocoon, namely Separation of Concerns (SOC) and Invers ion of Control (IoC). It also covers foundational aspects of the Avalon Framewor k, so you can have a better understanding on how Cocoon is structured. Cocoon helps you separate out concern areas for web development. The areas addre ssed are Logic, Content, Style, and Management. There are different mechanisms f or each. In order to learn how to use Cocoon, first make sure that you install it properl y, then investigate the many samples. The following screenshots come from the "t utorial" that is provided with Cocoon. After you have built the demo webapp as p er the installation instructions (build webapp) then you can see this tutorial i n action via the Samples pages. Note Screenshots are here. Separating Concerns Cocoon is designed to allow Developers, Business Analysts, Designers, and Admini strators to work with each other without breaking the other person's contributio n. The problem with using just JSPs, ASPs, or ColdFusion templates is that all o f the look, feel, and logic are intertwined. That means that maintenance is much more difficult, and the project's true costs are delayed until the customer wan ts feature enhancements or bugs fixed. This also means that if the site design i s introduced late in the game, the cost of revamping the site becomes much highe r. Developers Developer's jobs are to create the business logic and object model behind the we b application. They are more concerned with functionality than with layout or th e words displayed on a screen. These are the people that will develop the Action s (Components that only process information) and the hooks for how to get the ne cessary information from business objects. Business Analysts The Business Analysts are the people who are concerned with the words displayed on the screen, and to a certain extent, the layout. Typically, they will be usin

g the work done by the developer to put together a generic markup that will be t ransformed into the results. In small development environments, many times the d eveloper takes on both this role and the developer role. Typically, the business analyst will be working with the markup language that goes into the generator. Designers The designer is the person or group of people who are responsible to provide the final look and feel of a site. The designer does all the graphics and HTML code . In Cocoon, they will be working with the Transformers that take an input and s tructure it in a final presentation. Administrators The administrator is responsible for the sitemap which maps the URI space to the different pipelines in Cocoon. A pipeline is a path from a Generator to a Seria lizer. This means, that the administrator decides that all requests for a resour ce with a ".html" extension starts out as XML and ends up as HTML. The Administr ator will work closely with the Designers and the Developers. In the absence of a dedicated administrator, one developer should assume that role. It is importan t that developers do not get bogged down in this one Component. Development Style You have to decide early pective, or develop from of approaching the same , you will find that you approaches. on whether you will develop from a Business Markup pers a Document Markup perspective. They have different ways problem. Both approaches have its tradeoffs. In the end will need a combination of different aspects of the two

Business Markup Centric This approach makes the Business Object the center of attention for development. This approach formalizes your business objects, and makes sure that you always represent a business object in a standard manner. It's limitations come to bear when you have cases when you need two different objects that need to be represen ted on the same logical page. Document Markup Centric This approach feels the most natural to developers who come from backgrounds wit h scripting languages. This approach is a bit more flexible in that you represen t a page logically, with the wording as the center of attention. With this appro ach, it is up to the developer to ensure that the business object is represented in a consistent manner. Hybrid Approach We will develop a hybrid approach to development in this paper. What this means is that we start with a Document Markup Centric approach, and add in support for specific Business Markup as it is needed. In the end, this is the most flexible and maintainable method for development. The Concept For the sake of this paper, we are going to develop a very simple database-backe d application that manages users and departments. Each element has a name and an identifier. A department can have many employees, but each employee can only ha ve one department. We will be able to create, change, and delete both employees and departments. The SQL CREATE TABLE department { department_id INT NOT NULL, department_name VARCHAR (64) NOT NULL };

CREATE TABLE employee { employee_id INT NOT NULL, employee_name VARCHAR (64) NOT NULL, department_id INT NOT NULL }; ALTER TABLE department ADD PRIMARY KEY pkDepartment (department_id); ALTER TABLE employee ADD PRIMARY KEY pkEmployee (employee_id); ALTER TABLE employee ADD FOREIGN KEY department_id (department.department_id);Facilities Create Department (need name only) Update Department (change name, reassign potential employees to department, crea te employee for department) Delete Department Find Department (by name, or by ID) Create Employee (need name and department-create department if needed) Update Employee (change name, reassign department-create department if needed) Delete Employee Find Employees (by name, by ID, or by Department) Layouts Various screenshots are available as a separate document, to portray the layout of interfaces and results pages - apply your own style. Diving In In order to do anything in Cocoon, you will need a sitemap. At this point we wil l not go into detail but we will show you how to put an entry in so you can see your stuff. In most development situations, the sitemap will be set up for you. Since we want to start with a clean slate, take the sitemap that comes with Coco on's samples and clear out everything under the <map:pipelines> tag. Next, you w ill add an entry in the same location that looks like this: <map:pipeline> <map:match pattern=""> <map:redirect-to uri="home.html"/> </map:match> <map:match pattern="**.xml"> <map:generate src="docs/{1}.xml"/> <map:serialize type="xml"/> </map:match> <map:match pattern="**.html"> <map:generate src="docs/{1}.xml"/> <map:transform src="stylesheets/apache.xsl"/> <map:serialize/> </map:match> <map:match pattern="images/**.gif"> <map:read src="resources/images/{1}.gif" mime-type="image/gif"/> </map:match> <map:match pattern="images/**.jpg"> <map:read src="resources/images/{1}.jpg" mime-type="image/jpg"/> </map:match>

<map:match pattern="images/**.png"> <map:read src="resources/images/{1}.png" mime-type="image/png"/> </map:match> <map:match pattern="resources/**.css"> <map:read src="resources/styles/{1}.css" mime-type="text/css"/> </map:match> <map:match pattern="resources/**.js"> <map:read src="resource/styles/{1}.js" mime-type="application/x-javascript"/> </map:match> <map:handle-errors> <map:transform src="stylesheets/system/error2html.xsl"/> <map:serialize status-code="500"/> </map:handle-errors> </map:pipeline> What this does is tell the sitemap that we want to capture all URLs with a ".xml " extension, and find an equivalent file in the "docs" subdirectory. We are not performing any transformations at this time. The Sitemap is really a site admini strator's job to maintain. There are some exceptions to this general rule, but w e will discuss them when needed. We will use the Document Markup specified in th e StyleBook DTD format. Creating the Pages Since we are only looking at XML right now, we need to make sure our pages confo rm to the markup standards. You will see how well this comes in handy for debugg ing XSP (XML Server Pages) markup. Since we already have the Layout specified, a nd the database created, we will create our markup. Our home page is going to be really simple: a list of links that take us to the main pages. <document> <header> <title>Home Page</title> </header> <body> <s1 title="Welcome to Personnel Administrator"> <p> Welcome to our Personnel Administrator. You can perform one of the following functions: </p> <ul> <li> <link href="search-dept.html">Search Departments</link> </li> <li> <link href="search-empl.html">Search Employees</link> </li> <li> <link href="create-dept.html">Create Departments</link> </li> <li> <link href="edit-dept.html">Edit a Department</link> </li> <li>

<link href="create-empl.html">Create Employee</link> </li> <li> <link href="edit-empl.html">Edit an Employee</link> </li> </ul> </s1> </body> </document> Even though this doesn't look like much right now, we have two entries: "**.xml" and "**.html" for the same resource. Look at "home.html", and see how it looks now. Quite a difference. Don't remove the entry for viewing the page as XML yet. We need to use it to debug our XSP pages later. Our First Form For now, we are going to skip the search functionality, and jump to our "create" templates. It is important to realize the proper method of form handling. While it is possible to create XSP pages that perform the logic for you, this approac h is not very maintainable. We also have to choose whether we will directly acce ss the database, or encapsulate that logic in objects. The tradeoffs are that the direct SQL access is faster to get started, but that it is harder to maintain in the end. You may decide to start with the direct SQL access at the beginning of a project, and build the objects later. With that in mind, we will use some functionality that Cocoon has built in to make this appr oach a little easier. Cocoon has a group of Database actions that allow you to m ap form fields to dynamically created SQL calls. It also has a logicsheet that m akes creating SQL bound pages a little easier. Our first form is the "Create a Department" form. The website specification is m issing the tags for form building, we will provide an example here: <document> <header> <title>Department</title> </header> <body> <s1 title="Create a Department"> <form handler="create-dept.html"> <p> You can create a department by typing in the name and pressing the "submit" button. </p> <p> Name: <text name="name" size="30" required="true"/> </p> <submit name="Create Department"/> <note> * These fields are required. </note> </form> </s1> </body> </document> It is important to note that the "submit" tag is transformed into an HTML submit button with the name "cocoon-action-ACTIONNAME". The "cocoon-action-ACTIONNAME" form parameter is a magic value that Cocoon uses to select a specific action fr

om a group of actions that only gets executed at this page displays correctly, but does not ere the navigation goes once you click on the screen. What we are going to do is create one rtment and Employee pages.

during that time. You will find th do anything yet. The handler is wh "Create Department" button on the confirmation page for all the Depa

Cocoon has a FormValidatorAction that will take care of ensuring the input resul ts are acceptable. It also has the following database actions for your convenien ce: DatabaseAddAction, DatabaseUpdateAction, DatabaseDeleteAction, and DatabaseA uthenticatorAction. We will only need the Add, Update, and Delete actions for ou r simple webapp. In order to prepare them, we create an XML configuration file t hat tells the actions how to map request parameters to database tables and place constraints on the parameters. For the Department form group, it will look like this: <root> <!The "parameter" elements identify the root constraints for the FormValidatorAction. We are specifying that the "id" parameter is an integer (it limits to "long", "double", "boolean", and "string"). We are specifying that the "name" parameter is a string that is at least 5 characters--but no more than 64 characters. --> <parameter name="id" type="long"/> <parameter name="name" type="string" min-len="5" max-len="64"/> <!Each constraint set is used when we are defining a new way of validating a form. We define our constraint sets by function. Since we have the same basic form that is driving the FormValidator, we have an update set and an add set. Note that you can impose additional constraints than the default constraints listed above. Also, you do not "have" to enforce a constraint. Each "validate" element below identifies the parameter constraints we are enforcing. For more information view the JavaDocs for AbstractValidatorAction --> <constraint-set name="update"> <validate name="name"/> <validate name="id" nullable="no" min="1"/> </constraint-set> <constraint-set name="add"> <validate name="name"/> </constraint-set> <!-This is where we identify our table mappings so that the Database Actions can work their magic. Note that the parameter names are the same as above--as well as the same as form parameter names. First we tell the Database Actions that we are using the "personnel" connection pool we set up in <code>cocoon.xconf</code>. This file should be set up by the site administrator.

We also tell the Database Actions the structure of the table we will be populating. The keys are used to identify which columns will be treated as keys--they are treated different when the different SQL statements are created. Note that there is a "mode" attribute in the key element. The mode refers to how new keys will be generated. There are three modes: "automatic" keys are generated by the database, "manual" keys are generated by manually finding the largest value and incrementing it, and finally "form" keys take the key value from a parameter on the form. Both keys and values serve to map parameter names to table columns, converting the value into the native type. For a list of supported types check out the JavaDocs for AbstractDatabaseAction. --> <connection>personnel</connection> <table name="department"> <keys> <key param="id" dbcol="department_id" type="int" mode="manual"/> </keys> <values> <value param="name" dbcol="department_name" type="string"/> </values> </table> </root> After you create the descriptor file, you will have to create some entries in th e Sitemap so you can take advantage of the form descriptor. First, the Sitemap h as to be able to know how to reference the Actions we want. To do that, alter th e "map:actions" section to list all the actions we need: <map:actions> <map:action name="dbAdd" src="org.apache.cocoon.acting.DatabaseAddAction"/> <map:action name="dbDel" src="org.apache.cocoon.acting.DatabaseDeleteAction"/> <map:action name="dbUpd" src="org.apache.cocoon.acting.DatabaseUpdateAction"/> <map:action name="form" src="org.apache.cocoon.acting.FormValidatorAction"/> </map:actions> Lastly, we want to create an action set. An action set is a group of actions tha t will be applied at once. If the action set entry has an "action" parameter, th en the specific action is only executed when the ACTIONNAME of the magic "cocoon -action-ACTIONNAME" request parameter matches the value of the "action" paramete r. For our purposes, the action set we are defining is listed below (defined in the sitemap): <map:action-sets> <map:action-set name="process"> <map:act type="form" action="Create Department"> <map:parameter name="constraint-set" value="add"/> <map:act type="dbAdd"/> </map:act> <map:act type="form" action="Update Department">

<map:parameter name="constraint-set" value="update"/> <map:act type="dbUpd"/> </map:act> <map:act type="dbDel" action="Delete Department"/> </map:action-set> </map:action-sets> Now that we have defined the actions we want, with the parameters that control t hem during run-time, we can use it in our pipeline. <map:match pattern="*-dept.html"> <map:act set="process"> <map:parameter name="descriptor" value="context://docs/department-form.xml"/> <map:parameter name="form-descriptor" value="context://docs/department-form.xml"/> <map:generate type="serverpages" src="docs/confirm-dept.xsp"/> <map:transform src="stylesheets/apache.xsl"/> <map:serialize/> </map:act> <map:generate type="serverpages" src="docs/{1}-dept.xsp"/> <map:transform src="stylesheets/apache.xsl"/> <map:serialize/> </map:match> <map:match pattern="*-dept.xml"> <map:act set="process"> <map:parameter name="descriptor" value="context://docs/department-form.xml"/> <map:parameter name="form-descriptor" value="context://docs/department-form.xml"/> <map:generate type="serverpages" src="docs/confirm-dept.xsp"/> <map:serialize type="xml"/> </map:act> <map:generate type="serverpages" src="docs/{1}-dept.xsp"/> <map:serialize type="xml"/> </map:match> This may not seem clear what is happening right now. The way actions work is if they return a null, nothing inside the "map:act" entry will execute, and the req uest processing will flow through to the second "map:generate" section. This is a side affect of using the FormValidatorAction. If we choose to create our own b usiness objects and form validation framework, we are not constrained by this co nstruct. In addition, we changed the type of generator we are using: we have made it a "s erverpages" (or XSP) generator. We made the transition now so that we can report information on what failed to the user. First, we need to convert our "create-d ept.xml" file to an XSP page so that we can see the page again (right now we wil l get an error). To do this, simply add a new tag to the base of the document ca lled "xsp:page" declaring the XSP namespace. The change will look like this: <xsp:page xmlns:xsp="http://apache.org/xsp"> <!-- The original document will be embedded here --> </xsp:page> To complete the transformation, we usually change the extension to ".xsp" so we know what we are dealing with at a glance. Create a new file called "confirm.xsp

" with the following contents: <xsp:page xmlns:xsp="http://apache.org/xsp"> <document> <header> <title>Department</title> </header> <body> <s1 title="Department Processed"> <p> You have successfully processed the department. </p> </s1> </body> </document> </xsp:page> Adding support for Error Reporting In order to successfully report errors processing the page, add another namespac e declaration to the "xsp:page" element. The final form page will look like this : <xsp:page xmlns:xsp="http://apache.org/xsp" xmlns:xsp-formval="http://apache.org/xsp/form-validator/2.0"> <document> <header> <title>Department</title> </header> <body> <s1 title="Create a Department"> <form handler="create-dept.html"> <p> You can create a department by typing in the name and pressing the "submit" button. </p> <p> Name: <text name="name" size="30" required="true"/><br /> <xsp:logic> if (<xsp-formval:is-toosmall name="name"/>) { <xsp:text>"Name" must be at least 5 characters</xsp:text> } else if (<xsp-formval:is-toolarge name="name"/>) { <xsp:text>"Name" was too long</xsp:text> } </xsp:logic> </p> <submit name="Create Department"/> <note> * These fields are required. </note> </form> </s1> </body> </document> </xsp:page> Adding Database Support with the ESQL Logicsheet The "Create Employee" page is going to require database access so that we know w hich Department a new employee is assigned to. This is fairly easy to accomplish

with the ESQL Logicsheet. Again, when you use the ESQL logicsheet, you lose som e of your separation of concerns. <xsp:page xmlns:xsp="http://apache.org/xsp" xmlns:xsp-formval="http://apache.org/xsp/form-validator/2.0" xmlns:esql="http://apache.org/cocoon/SQL/v2"> <document> <header> <title>Employee</title> </header> <body> <s1 title="Create an Employee"> <form handler="create-empl.html"> <p> You can create a department by typing in the name and pressing the "submit" button. </p> <p> Name: <text name="name" size="30" required="true"/><br /> <xsp:logic> if (<xsp-formval:is-null name="name"/>) { <xsp:text>"Name" cannot be empty</xsp:text> } else if (<xsp-formval:is-toolarge name="name"/>) { <xsp:text>"Name" was too long</xsp:text> } </xsp:logic> </p> <p> Department: <select name="department"> <esql:connection> <!-- declare the connection pool we are using --> <esql:pool>personnel</esql:pool> <!-- query execution blocks can be repeated --> <esql:execute-query> <!-- Find all departments and order them --> <esql:query> SELECT department_id, department_name FROM department ORDER BY department_name </esql:query> <!-- What to do with the results --> <esql:results> <!-A successful query that returns results executes this block. You can also embed more "execute-query" blocks inside the row-results. That way you can have queries that filter information based on the results of other queries. --> <esql:row-results> <option> <xsp:attribute name="name"> <esql:get-string column="department_id"/> </xsp:attribute>

<esql:get-string column="department_name"/> </option> </esql:row-results> <!-Other result types are "no-results" and "error-results". A successful query that does not return results (an empty resultset) will use the XML embedded in the "no-results" section. An unsuccessful query that throws an exception will use the XML embedded in the "error-results" section. --> </esql:results> </esql:execute-query> </esql:connection> </select> </p> <submit name="Create Employee"/> <note> * These fields are required. </note> </form> </s1> </body> </document> </xsp:page> As you can see ESQL is flexible and powerful, but the cost of that flexibility i s a loss of readability. Using a logicsheet to wrap information in a business ob ject is another alternative. Notice how ESQL works: First, we specify our connection information which will apply to all queries in the ESQL structure. Next, we specify our first query we are going to use. Note that you can nest que ries as well as have more than one in an "esql:connection" element. Lastly, we specify how we process the results. There are three different types o f results: "esql:row-results", "esql:no-results", and "esql:error-results". This allows you to handle different scenarios easily. It is inside the individual re sults elements that we can nest new queries to process. A Note About Actions Actions are the bread and butter of logic processing in Cocoon. There are a numb er of approaches that you can take when developing Actions. You can create a spe cific action for each piece of business logic. This approach is very heavy hande d and requires you to spend a lot of development time creating actions. The preferred method for creating actions is to provide a generic action that ca n handle a wide range of specific actions. The Database Actions and Validator Ac tions are examples of this approach. They will read a configuration file specifi ed by a parameter, and they will modify the specific results based on the config uration file. In order to take advantage of this for your own Actions, you can e xtend the AbstractComplimentaryConfigurationAction. Basically what it does is en capsulate the logic for reading and caching the Configuration information for yo ur Action. Redirects Most web developers agree that redirecting a user based on input is a valuable a nd necessary part of web development. In Cocoon there are only two locations whe re you can issue redirects: the Sitemap and Actions. In essence, Cocoon does req uire you to plan so that redirects are only used when necessary.

One approach that is good to use is to require all traffic to go through a URL c ontrolling action. The Action will test to see if the user is logged in, and if not will send them to the login page. Another derivation on this approach is to test for a user's role, and if they do not have access redirect them to a differ ent page. Writing an Action Writing an action is as simple as writing a Component that conforms to the Actio n interface. Be sure to examine the different Actions that are in the org.apache .cocoon.acting package - you might find some abstract actions that you can exten d. Actions are Avalon Components, so you may want to read Avalon's Whitepaper fo r more information. Note Actions will return a map that contains values that the sitemap administrator ca n use in the sitemap. If the Action returns a null, then anything inside the "ma p:act" element will not be executed. Return Values The Action interface specifies that it returns a Map. This Map is used for value substitution in the sitemap, and communicating information to other Actions. Wh en an Action is specified in the sitemap, it uses the following syntax: <map:act type="my-action"> <map:generate src="{source}"/> <map:transform src="doc2{theme}"/> <map:serialize/> </map:act> The above code snippet assumes you have an Action with the name "my-action" alre ady specified. It also assumes that there are two "parameters" returned from the action in the Map. The sitemap queries the returned Map for the "source" and "t heme" values, and substitutes their values in place of the curly braces that ref erenced it. In other words, when it sees the "map:generate" with an src attribut e of "{source}" it looks in the Map. For our discussion, let us say the value st ored is "index.xml". The Sitemap will perform the substitution so that the src a ttribute now containts "index.xml". In the case that the above the action might return a null value. In that case, e verything inside the "map:act" element is skipped. You can use this to good adva ntage like the *ValidatorActions do. If everything is validated correctly, they return a Map. If there is an error, they return a null, and place the informatio n in Request attributes. Cocoon Supplied Components Cocoon supplies a number of different Components for your use. The types of Comp onents we will discuss here are Generators, Transformers, Serializers, Readers, and Actions. This are the important Components that allow you to do you job. Generators A Generator will create SAX events for a SAX stream-whether it reads from an inp ut stream or it generates it on the fly. All built in generators are in the pack age "org.apache.cocoon.generation". DirectoryGenerator Reads a directory, and builds an XML document based on the contents. You can pas s parameters to it to control how it behaves (note parameter names are case sens itive): dateFormat - a format string that you would use in the Java SimpleDateFormat obj

ect depth - the maximum number of directories deep the generator will look (defaults to 1) root - a regular expression to find the root directory include - a regular expression to declare the files/directories that will be inc luded in the list exclude - a regular expression to declare the files/directories that will not be included in the list When you use this Generator, you must have the Jakarta Regexp package installed in your WEB-INF/libs directory. Also, the DirectoryGenerator is not Cacheable so the results will be generated fresh each time. The resulting XML looks like this: <?xml version="1.0"?> <directory xmlns="http://apache.org/cocoon/directory/2.0" name="C:\path\dir\" lastModified="135432153351" date="11 Jun 2001"> <file name="C:\path\dir\file.xml" lastModified="135432153351" date="11 Jun 2001"/> </directory> FileGenerator This generator and the ServerPagesGenerator will be your most used generators. T he FileGenerator reads an XML file from an input source, and converts it into a SAX stream. When you use this Generator, you must have a JAXP 1.1 compliant parser installed in your WEB-INF/libs directory. You may also use the Xerces parser bypassing th e JAXP requirement. The FileGenerator is Cacheable, so the results will only be re-read when the file changes. FragmentExtractorGenerator This generator is used in conjunction with the FragmentExtractorTransformer (mor e on that in the transformers section). The FragmentExtractorTransformer splits an XML document into smaller parts so you can treat each smaller part as a uniqu e document. To see this in action, check out the Cocoon supplied samples and cli ck on the SVG Welcome page. This Generator caches the results from the FragmentExtractorTransformer for quic k retrieval later. It is Cacheable, so the fragments are generated once and the cached version is read from that point forward. HTMLGenerator This generator is used to read in an HTML file that may not be properly formatte d to comply with XML standards. The result is properly formatted XHTML. This generator requires the Tidy.jar file installed in the WEB-INF/libs director y. The HTMLGenerator is Cacheable, so the results can be cached for application speedup. ImageDirectoryGenerator This generator is an extension of the DirectoryGenerator, so it has the same req uirements. It extends the markup to include two new attributes for the "file" el ement: "height" and "width". The ImageDirectoryGenerator reads every GIF and JPE G file to get the dimensions.

This generator is not Cacheable (just like the DirectoryGenerator). JspGenerator This generator executes a JSP file and parses the result. The JSP must generate valid XML, and be a file in the context. This generator requires a JAXP 1.1 compliant parser or Xerces if your environmen t will not allow you to install one. It is also not cacheable so the results are generated each time. PhpGenerator This generator functions just like the JspGenerator, but with PHP templates. The PHP must generate valid XML, and be a file in the context. This generator requires a JAXP 1.1 compliant parser and the phpservlet.jar file that comes from http://php.net. Install the files in the WEB-INF/libs directory. The PhpGenerator is not Cacheable. RequestGenerator This generator converts the Request object into an XML representation. It is bes t used for debugging purposes. The resulting XML follows: <request xmlns="http://apache.org/cocoon/request/2.0" target="index.html" source="context://docs/index.xml"> <requestHeaders> <header name="HOST_NAME">johny-bravo.infoplanning.com</header> <!-- repeat for each header --> </requestHeaders> <requestParameters> <parameter name="form-param"> <value>1</value> <!-- repeat for each value in "form-param" --> </parameter> <!-- repeat for each parameter --> </requestParameters> <configurationParameters> <parameter name="configurations">context://WEB-INF/cocoon.xconf</parameter> <!-- repeat for each parameter --> </configurationParameters> </request> The RequestGenerator does not have any special requirements for libraries, and i t is not Cacheable. ScriptGenerator The ScriptGenerator uses the Bean Scripting Framework (BSF) and an associated in terpreter to generate valid XML. If you add language support, you will have to e mbed the following configuration information: <add-languages> <!-- repeat the following for each language: --> <language name="kawa-scheme" src="org.gnu.kawa.bsf.engines.KawaEngine"> <extension>scm</extension>

<!-- repeat for each file extension --> </language> </add-languages> The ScriptGenerator requires that you have the bsf.jar in your WEB-INF/libs dire ctory along with any jars for the script interpreters you use. The ScriptGenerat or is not Cacheable. ServerPagesGenerator The ServerPagesGenerator is the XML Server Pages (XSP) engine. It automatically compiles a new Generator at runtime based on an input XML file. This generator requires that you have a JAXP 1.1 compliant parser and XSLT engin e installed in your WEB-INF/libs directory. It also requires you to have the JDK 's tools.jar file in your classpath. If you reference any packages, they must al so be in your classpath. The created generator is not Cacheable. StatusGenerator The StatusGenerator is another debug tool. It provides status information for th e Cocoon engine. The resultant XML is in the following format: <statusinfo xmlns="http://apache.org/cocoon/status/2.0" xmlns:xlink="http://www.w3.org/1999/xlink" host="johnny-bravo.infoplanning.com" date="7/16/2001 1:16:42 pm"> <group name="vm"> <group name="memmory"> <value name="total"><line>5213255</line></value> <value name="free"><line>12321211</line></value> </group> <group name="jre"> <value name="version"><line>1.3.1</line></value> <value name="java-vendor" xlink:type="simple" xlink:href="http://java.sun.com/jdk/1.3/"> <line>Sun Microsystems Inc.</line> </value> </group> <group name="operating-system"> <value name="name"><line>Windows 2000</line></value> <value name="architecture"><line>x86</line></value> <value name="version"><line>5.0</line></value> </group> </group> <value name="classpath"> <line>C:\tomcat\lib\tomcat.jar</line> <line>C:\jdk1.3.1\lib\tools.jar</line> </value> </statusinfo> The results are not cacheable, and do not require any special libraries. StreamGenerator The StreamGenerator is used to convert the Request's InputStream into a SAX XML stream. Alternately, it will accept the magic form parameter "form-name" and rea d the input stream that the parameter points to. This generator requires the JAXP 1.1 compliant parser (or Xerces). It is not cac heable.

VelocityGenerator The VelocityGenerator is used to convert the output from the Velocity template e ngine to a valid XML stream. This generator requires Jakarta Velocity and a JAXP 1.1 compliant parser install ed in WEB-INF/libs. It is not Cacheable. Transformers Transformers read a SAX stream, manipulate the XML stream, and send the results to the next Component in the chain. All built in generators are in the package " org.apache.cocoon.generation". CIncludeTransformer The CIncludeTransformer looks for instances of the "ci:include" element, and wil l embed another XML resource in your document. That resource can be in the sitem ap so you can include the results of processed XSP pages. An example follows: <document xmlns:ci="http://apache.org/cocoon/include/1.0"> <ci:include src="cocoon://my-resource.xml" element="body" ns="http://mycompany.com/my-resource/1.0" prefix="res"/> </document> The Transformer will read the results from the sitemap, and embed it into this d ocument with a new root element "body" using a new namespace (xmlns:res="http:// mycompany.com/my-resource/1.0"). The results are not cached. FilterTransformer The FilterTransformer will look for instances of an element you specify using pa rameters, and will not forward any SAX events for that element or any child elem ents. You can pass parameters to it to control how it behaves (note parameter na mes are case sensitive): element-name - The name of the element to filter count - the number of times the element will be filtered blocknr - the element number that filtering begins FragmentExtractorTransformer This is transformation half of the FragmentExtractor. This transformer sieves an incoming stream of xml with embedded SVG images and replaces the images with a xlink locator pointing to the image. Ultimately this could be much more general, but currently it is mainly an SVG extraction. I18nTransformer This is Cocoon's port of Infozone Group's I18nProcessor. The word i18n is a shor thand for the longer word "internationalization" (starts with 'i', ends with 'n' , and has 18 letters in the middle). The internationalization transformer allows you to look up references by key in an XML dictionary. This allows you to suppo rt your same business processes in many different countries. You have to pass pa rameters to it so that it knows how to process i18n requests: default_lang - The default language if the requested language does not exist (tw o character country code) avalailable_lang_X - Language available by the dictionary (two character country code). Replace the 'X' in the attribute with a number (1, 2, 3). src - The location of the dictionary file. The I18nTransformer reads the request parameter "lang" to determine which langua ge to display to the user. To translate text either embed the text inside the "i

18n:text" element, or the attribute name inside the "i18n:attr" attribute. <document xmlns:i18n="http://apache.org/cocoon/i18n/2.0"> <body> <s1 title="Test Title" i18n:attr="title"> <p> <i18n:text>This is replaceable text.</i18n:text> </p> </s1> </body> </document> LDAPTransformer The LDAPTransformer is a class that can be plugged into a pipeline to transform the SAX events which passes through this transformer into queries an responses t o/from a LDAP interface. The Sitemap This section is meant primarily as a reference for the Sitemap Manager. The pers on in this role needs to have a better understanding of the sitemap than any oth er role. The sitemap is a relatively new concept, and as such is subject to refi nement. There have been a couple of proposals to replace it with something else, but nothing has been started yet. The Sitemap is composed of three major parts: component declaration, resource de claration, and pipeline declaration. You will only use a few different types of components in the sitemap: Generators, Transformers, Serializers, Readers, Match ers, Selectors, and Actions. Generators create XML and pass the results in a SAX stream. Transformers read a SAX stream and manipulate the results on the way th rough. Serializers read a SAX stream, and convert it into the servlet's output s tream. Readers read an input stream and copy the results to the servlet's output stream. Matchers and Selectors are used to choose how to process an incoming re quest. Lastly, Actions are used to perform logic only functions (no display logi c). Below is the root element of all sitemaps: <map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0"> </map:sitemap> Choosing your Components As previously discussed, you may choose a number of components to use in your ow n system. This section identifies the different components you can use, and what they do. Before we begin, I must state that every component is declared in the "map:components" element of the Sitemap: <map:components> </map:components> Generators All generators are declared within the "map:generators" element that is a child of the "map:components" element: <map:generators> <map:generator name="file" src="org.apache.cocoon.generation.FileGenerator"/>

</map:generators> Most Generators do not have configuration information, so the "map:generator" el ement is left empty. If there were configuration information to pass to the gene rator, it would be placed inside the element. As you can see in the sitemap snip pet above, you declare a generator with the "map:generator" element, a "name" at tribute, and a "src" attribute. The "name" attribute is how you will refer to th is specific type of generator from this point forward. The "src" attribute is th e fully qualified class name of the Generator class. In fact this construct is t he same for all component types - the only thing that changes is the elements th at declare the type of Component we are dealing with.