OTN XMLNews Application

Table Of Contents 

This document is organized into following sub-sections:

• Overview of the sample application
• Application Usecase Diagram
• Application Database Schema Diagram
• Application Architecture Diagram
• User Notes with Screen Shots
• Installation and Configuration
• Description of Sample files

        The Dynamic News is Oracle XML DB based application that manages News Items for a web-site providing static/customized News Service. The News Items are stored in the database. When the user requests for the news page, the HTML for the static/customized news page is generated and returned to the user.

        Basically, this sample application implements management of News Items for a Website that provides a Dynamic/Customized News Service.   (Example: myCNN).

         Functionally, when the sample application is invoked, the main page(Home page) presents a set of features like:

1. Top News
2. Main News Headlines
3. User login and preferences
4. Feedback option    
5. Search news options 

         Any user can customize the news he wants to see as 'My News' page. This link is available from the main page left navigation option. To use customization feature, the user has to register/login first. User customization involves creation of the user profile by selecting News Categories or SubCategories or Types. If the user selects Categories/Sub Categories/Types in his/her profile, dynamic news generation will take place which displays user preferred news.

       The news generation technique is explained below. The Admin user will maintain and generate the news for the application. Admin logs on with username/password as admin/admin. He can create users with different roles. The roles are 'admins', 'newsprovider', 'manager' and 'enduser'.  Admin has the role of 'admins' and is the super user who has all control over the application. The newsproviders can only upload/feed the news to the application.  The 'manager' has all the admin activity privileges for categories/subcategories/types.

  The approval and archival of the uploaded News Items can be done only by Admin. The Admin and manager can also upload/edit/delete the News Items. Additionally, the Admin can create/edit/delete News Categories, Sub Categories and Types. One of the main admin activities involves generation of the news. Admin is involved in Batch/static news Generation. Other activities of admin include managing Newsletter, guest book and archives. News generation activities include: Batch news which includes main content news and Top five news. Generating Newsletter also is in Admin's control. Additionally, Admin is involved in importing News. 

Batch/Static News Generation:
Periodically, the admin will generate the news for the application. He can decide to generate the main page news or news for different Categories and SubCategories. Only approved news will be used in the generation. To generate the news HTML page, XSL is applied on the news information which is retrieved as XML document. 

Dynamic News generation:
Here, the user profile will allow customization level up to Categories, Sub Categories and Types. Data is directly retrieved from the database without the Admin's involvement. Here again, appropriate XSL is applied and the HTML news page is generated.

News Import in RSS format:

Admin can import XML documents that conform to the Rich Site Summary ( RSS) standard. Developed by Netscape as a way to share data channels, RSS has been used at Web sites such as my.netscape.com and slashdot.org. The news title and description are imported to the application and saved in the database. As an example, site.xml file is shipped with the sample. This is under xmlnews/config directory. Please see Description of Sample files for directory structure and file description. This file is in RSS format and can be used to import news items to the application.

J2EE Form-based Authentication:

   The XMLNews sample application makes use of form based authentication mechanism for allowing access to application information. Here, the web container implements authorization on Web resources of application, using security roles defined in the deployment descriptor (principals.xml and web.xml) of the application.

  The Web container activates the authentication mechanism that has been configured for that resource, when protected Web resources are accessed. It performs the following steps to implement security of a Web application.

• Determines whether the user has been authenticated when the protected Web resources are accessed.

• If the user has not been authenticated yet, requests that the user provide security credentials by redirecting to the login page defined in the deployment descriptor.

• Validates the user's credentials against the database information by making use of configuration of the container.

  Basically, the container will restrict resources based on a given URL pattern by making use security roles that are defined in web.xml to allow access to the resources. The groups and roles are mapped in orion-application.xml file. All the groups are listed in principals.xml.

Database validation of the user:
The XMLNews application makes use of Orion's SimpleUserManager.java class for implementing a custom User Manager that validates username/password against Oracle database table values. Orion-application.xml will define this user manger class used for validation of the user.  In the current application, the custom class is created as MyUserManager.java that extends Orion's SimpleUserManager.java class.

OTN XMLNews Web Service:

The application provides a webservice endpoint which exposes a method: getAllNews as a web service. Through this endpoint other clients can consume this webservice. The exposed webservice interface has following configuration:

Input parameter: 
A String that takes in a date value in 'DD-MON-YYYY' format. This will get all the news for that particular day.

Out Parameter:
A String array which contains title and description of the retrieved news items for the specified date. The title and description are separated by '##'. Any client which has to consume this webservice has to write necessary client application to access and get the news items.

The URL to access the webservice is as follows:

http://<hostname>:<oc4j_port>/xmlnews/OtnDynamicNewsService

Architecture Explanation:
OTN XML News, a multi-tier application consists of components communicating across tiers to access and exchange data standardizing on the Java 2 Platform, Enterprise Edition (J2EE) and leverages technologies like:

• Java and XML for platform-neutral application logic and data exchange
• JDBC for accessing enterprise data in relational databases using SQL
• Java Servlets and JavaServer Pages for building dynamic, browser-based interfaces
• Enterprise JavaBeans for implementing transactional business components. 

• Model/View/Controller (MVC) Pattern
• Session Façade Pattern
• Value Object Pattern
• Page-by-Page Iterator Pattern
• Fast-Lane Reader Pattern
• Connection Façade Pattern

The application uses JSPs which implement JSP templates for building dynamic, browser-based interfaces. The request to the View comes from the browser client. Enterprise JavaBeans are used for implementing transactional business components along with few Reader Classes and utility classes.

  In the Controller Layer, the RouterServlet functions as the controller which dispatches browser requests to other controller objects like UserController, NewsController, BatchController etc.  The Controllers will make use of Service Locators to look up the required service component for every request.

  The Model layer of the application is divided into two as Services Layer and Business Layer. The Services Layer presents different services for different business entities i.e. EJBs. This layer separates the presentation and the business layer. The services are implemented as Stateless Session Beans which talk to the EJBs in the Business Layer.  The lookup to the EJBs is done using Service Locators.

  In the Services Layer, a method in the NewsService Session Bean is exposed as a Web Service. News Exports can be done from this News Web Service.

  The Business Layer will encompass Entity EJBs, Value Objects and Reader Classes. The Entity EJBs in the application viz.. Category, Type, Feedback, User, which are implemented as CMP beans. NewsItem is implemented as a stateless session Bean to manage news information using Oracle XMLTYPE datatype. Oracle XML DB features are used in NewsItemSession Bean.

  The DB Access Abstraction Layer is a re-useable library through which database connections are managed. This layer is used by BMP EJB - NewsItem and the Reader Classes where as the EJB Container takes care of managing database connections for the other CMPs.

  When the application is invoked, the first page displayed is the Home page which looks as in Figure below. This page does not require any login. Any user who invokes the URI will see this page first. The page displays left navigation options, main news content, right navigation(which has top five news). Below main content lies top five news content.

All URIs starting with 'auth' will have be authenticated. For example: 'authLogin'.  The application uses Form based authentication for implementing this. Mainly, the admin activities will require login to be validated and authenticated. Also, to access customized or user preferred news, authentication is required. Below is the login page to which all login call will be directed.

Any registered user of the application can set his/her preferences to see news from the application. The URI: /authMain will get the XMLNews from the database by dynamically generating the content based on user preferences. An example  page is shown below.

News Adminstration related users will have roles like: admins, manager or newsprovider. All of these user roles will be allowed different news administration activities.The page shown is the page displayed for the user with 'admins' role.

The page shown is the page displayed for the user with 'manager' role. The manager can manage categories, subcategories and types. He can also create/edit/query News Items.

The page shown is the page displayed for the user with 'newsprovider' role. Newsproviders can only create News Items.

Refer to Install.html file present in the sample jar for step-by-step instructions on extracting files, installing and configuring any other systems to successfully run this application.

The directory structure of the xmlnews.jar is as shown below :

Here xmlnews is the top level directory.