NewsML Toolkit Version 1.1 12 December 2001 ************************************************************************ Copyright (c) 2001 by Reuters PLC Copyright (c) 2000 by Reuters PLC and Wavo Company, Inc. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA ************************************************************************ This distribution contains the final release of version 1.1 of the NewsML Toolkit, a Java-based library for processing NewsML documents. The latest version of the library is available at http://newsml-toolkit.sourceforge.net/ Contents -------- README - this file. CHANGES - a high-level summary of changes in each version ChangeLog - a detailed log of code changes Copying - license information. build.xml - a project file for Apache's Ant build tool. newsml-explorer.jar - executable JAR file of the demo app with all required libraries included. newsml-toolkit.jar - the NewsML Toolkit in a single JAR file (without the additional required libraries). docs/ - documentation (see docs/index.html) classes/ - compiled Java class files lib/ - additional libraries used by the NewsML Toolkit src/ - source code for the NewsML Toolkit Prerequisites ------------- The NewsML Toolkit requires a Java system compatible with JDK 1.2/ Java2 or higher (tested with JRE and HotSpot version 1.3.1 on a Linux 2.4-based system). The toolkit also requires the following additional, open-source Java libraries: 1. An XML parser supporting SAX2 and DOM level 2 (tested with Xerces-J 1.4.0). The DOM level 2 interfaces are also required, but they will usually be bundled with the parser. 2. SAXPath (tested with version 1.0beta5). 3. Jaxen (tested with version 1.0beta6). If you wish to rebuild the NewsML Toolkit from source, you will also require the following library: 4. Ant (tested with version 1.4). If you wish to run the unit tests, you will also require the following library: 5. JUnit (tested with version 3.7). If you wish to run the conformance-testing tools, you will also require the following library: 6. Gnu Regular Expression library (tested with 1.1.3). JAR files for all of these except Ant and JUnit come bundled in the lib/ subdirectory and are built-into the newsml-explorer.jar file as well. If you would like to see the source code, to download them separately, or just to obtain more information, you can go to the following home pages: Ant: http://jakarta.apache.org/ant/ DOM: http://www.w3.org/DOM/ Jaxen: http://jaxen.sourceforge.net/ JUnit: http://www.junit.org/ SAXPath: http://saxpath.sourceforge.net/ Xerces: http://xml.apache.org/xerces-j/ Gnu RE: http://www.cacas.org/~wes/java/ Running the Demo ---------------- You can try running the demo program NewsML Explorer by typing java -jar newsml-explorer.jar For further details, see docs/demos.html. Getting Started --------------- The NewsML Toolkit contains an abstract set of interfaces that do not depend on any specific implementation, together with an implementation that wraps around a Document Object Model (DOM) tree:any conformant Java-based DOM library may be used, though the demonstration application looks for Apache's Xerces library. To begin processing a NewsML tree, you need a NewsMLFactory. To get a factory to build a DOM/Xerces implementation, try NewsMLFactory factory = new DOMNewsMLFactory(new XercesDOMFactory()); If you're not using Xerces, you'll need to provide your own implementation of the (very simple) org.newsml.toolkit.dom.DOMFactory interface. Other implementations will provide their own factories. Next, to create a new NewsML object tree based on a URL, use something like the following: NewsML newsml = factory.createNewsML(url); This procedure will throw an IOException if there's any error reading or building the document. Next, you can use the query methods on the newsml object to get information and to dig down into the package. See the org.newsml.toolkit.NewsML documentation for details. Demonstration Application ------------------------- There is a simple demonstration application available. The demo requires a Java2-conformant JVM and the Apache Xerces XML library. The usage is java -jar newsml-explorer.jar [url] or (with the appropriate JAR files on your classpath) java NewsMLExplorer [url] Where the optional [url] argument is the URL of a NewsML package that you would like to view. A tree outline of the package will appear on the left side of the window, and a tabular summary will appear on the right. -- newsml-toolkit-users@lists.sourceforge.net