Modified: poi/site/publish/components/hpsf/how-to.html URL: http://svn.apache.org/viewvc/poi/site/publish/components/hpsf/how-to.html?rev=1836244&r1=1836243&r2=1836244&view=diff ============================================================================== --- poi/site/publish/components/hpsf/how-to.html (original) +++ poi/site/publish/components/hpsf/how-to.html Wed Jul 18 23:27:21 2018 @@ -1,154 +1,294 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd";> +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd";> <html> <head> <META http-equiv="Content-Type" content="text/html; charset=UTF-8"> -<!--*** This is a generated file. Do not edit. ***--> -<link rel="stylesheet" href="../skin/tigris.css" type="text/css"> -<link rel="stylesheet" href="../skin/mysite.css" type="text/css"> -<link rel="stylesheet" href="../skin/site.css" type="text/css"> -<link media="print" rel="stylesheet" href="../skin/print.css" type="text/css"> +<meta content="Apache Forrest" name="Generator"> +<meta name="Forrest-version" content="0.9"> +<meta name="Forrest-skin-name" content="pelt"> <title>HPSF HOW-TO</title> +<link type="text/css" href="../../skin/basic.css" rel="stylesheet"> +<link media="screen" type="text/css" href="../../skin/screen.css" rel="stylesheet"> +<link media="print" type="text/css" href="../../skin/print.css" rel="stylesheet"> +<link type="text/css" href="../../skin/profile.css" rel="stylesheet"> +<script src="../../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../../skin/fontsize.js" language="javascript" type="text/javascript"></script> +<link rel="shortcut icon" href="../../images/favicon.ico"> </head> -<body bgcolor="white" class="composite"> -<!--================= start Banner ==================--> -<div id="banner"> -<table width="100%" cellpadding="8" cellspacing="0" summary="banner" border="0"> -<tbody> -<tr> -<!--================= start Group Logo ==================--> -<td width="50%" align="left"> -<div class="groupLogo"> -<a href="https://www.apache.org";><img border="0" class="logoImage" alt="The Apache Software Foundation" src="../resources/images/asf_logo.png"></a> -</div> -</td> -<!--================= end Group Logo ==================--> -<!--================= start Project Logo ==================--><td width="50%" align="right"> -<div align="right" class="projectLogo"> -<a href="https://donate.apache.org/";><img border="0" class="logoImage" alt="Support Apache" src="../resources/images/support-asf.png" width="120" height="120" title="Your donation helps The Apache Software Foundation ensure its community-driven software remains available to billions of users at absolutely no cost."></a><a href="https://poi.apache.org/";><img border="0" class="logoImage" alt="Apache POI" src="../resources/images/pb-poi.png" width="120" height="120" title="Apache POI - the Java API for Microsoft Documents"></a> +<body onload="init()"> +<script type="text/javascript">ndeSetTextSize();</script> +<div id="top"> +<!--+ + |breadtrail + +--> +<div class="breadtrail"> +<a href="https://www.apache.org";>Apache Software Foundation</a> > <a href="https://poi.apache.org";>Apache POI</a><script src="../../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script> +</div> +<!--+ + |header + +--> +<div class="header"> +<!--+ + |start group logo + +--> +<div class="grouplogo"> +<a href="https://www.apache.org";><img class="logoImage" alt="Apache Software Foundation" src="../../images/group-logo.png" title="The Apache Software Foundation is a cornerstone of the modern Open Source software ecosystem – supporting some of the most widely used and important software solutions powering today's Internet economy."></a> +</div> +<!--+ + |end group logo + +--> +<!--+ + |start Project Logo + +--> +<div class="projectlogo"> +<a href="https://poi.apache.org";><img class="logoImage" alt="Apache POI" src="../../images/project-logo.png" title="Apache POI is well-known in the Java field as a library for reading and writing Microsoft Office file formats, such as Excel, PowerPoint, Word, Visio, Publisher and Outlook. It supports both the older (OLE2) and new (OOXML - Office Open XML) formats."></a> +</div> +<!--+ + |end Project Logo + +--> +<!--+ + |start Search + +--> +<div class="searchbox"> +<form action="http://www.google.com/search"; method="get" class="roundtopsmall"> +<input value="poi.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google"> + <input name="Search" value="Search" type="submit"> +</form> </div> -</td> -<!--================= end Project Logo ==================--> -</tr> -</tbody> -</table> +<!--+ + |end search + +--> +<!--+ + |start Tabs + +--> +<ul id="tabs"> +<li> +<a class="unselected" href="../../index.html">Home</a> +</li> +<li> +<a class="unselected" href="../../help/index.html">Help</a> +</li> +<li class="current"> +<a class="selected" href="../../components/index.html">Component APIs</a> +</li> +<li> +<a class="unselected" href="../../devel/index.html">Getting Involved</a> +</li> +</ul> +<!--+ + |end Tabs + +--> </div> -<!--================= end Banner ==================--> -<!--================= start Main ==================--> -<table width="100%" cellpadding="0" cellspacing="0" border="0" summary="nav" id="breadcrumbs"> -<tbody> -<!--================= start Status ==================--> -<tr class="status"> -<td> -<!--================= start BreadCrumb ==================--><a href="https://www.apache.org/";>Apache</a> | <a href="https://poi.apache.org/";>POI</a><a href=""></a> -<!--================= end BreadCrumb ==================--></td><td id="tabs"> -<!--================= start Tabs ==================--> -<div class="tab"> -<span class="selectedTab"><a class="base-selected" href="../index.html">Home</a></span> | <script language="Javascript" type="text/javascript"> -function printit() { -if (window.print) { - window.print() ; -} else { - var WebBrowser = '<OBJECT ID="WebBrowser1" WIDTH="0" HEIGHT="0" CLASSID="CLSID:8856F961-340A-11D0-A96B-00C04FD705A2"></OBJECT>'; -document.body.insertAdjacentHTML('beforeEnd', WebBrowser); - WebBrowser1.ExecWB(6, 2);//Use a 1 vs. a 2 for a prompting dialog box WebBrowser1.outerHTML = ""; -} -} -</script><script language="Javascript" type="text/javascript"> -var NS = (navigator.appName == "Netscape"); -var VERSION = parseInt(navigator.appVersion); -if (VERSION > 3) { - document.write(' <a title="PRINT this page OUT" href="javascript:printit()">PRINT</a>'); -} -</script> </div> -<!--================= end Tabs ==================--> -</td> -</tr> -</tbody> -</table> -<!--================= end Status ==================--> -<table id="main" width="100%" cellpadding="8" cellspacing="0" summary="" border="0"> -<tbody> -<tr valign="top"> -<!--================= start Menu ==================--> -<td id="leftcol"> -<div id="navcolumn"> -<div class="menuBar"> -<div class="menu"> -<span class="menuLabel">Apache POI</span> - -<div class="menuItem"> -<a href="../index.html">Top</a> +<div id="main"> +<div id="publishedStrip"> +<!--+ + |start Subtabs + +--> +<div id="level2tabs"></div> +<!--+ + |end Endtabs + +--> +<script type="text/javascript"><!-- +document.write("Last Published: " + document.lastModified); +// --></script> </div> - +<!--+ + |breadtrail + +--> +<div class="breadtrail"> + + + </div> +<!--+ + |start Menu, mainarea + +--> +<!--+ + |start Menu + +--> +<div id="menu"> +<div onclick="SwitchMenu('menu_selected_1.1', '../../skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('../../skin/images/chapter_open.gif');">Component APIs</div> +<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;"> +<div class="menuitem"> +<a href="../../components/index.html">Overview</a> </div> -<div class="menu"> -<span class="menuLabel">HPSF</span> - -<div class="menuItem"> -<a href="index.html">Overview</a> +<div class="menuitem"> +<a href="../../apidocs/index.html">Javadocs</a> </div> - -<div class="menuItem"> -<span class="menuSelected">How To</span> +<div onclick="SwitchMenu('menu_1.1.3', '../../skin/')" id="menu_1.1.3Title" class="menutitle">Excel (HSSF/XSSF)</div> +<div id="menu_1.1.3" class="menuitemgroup"> +<div class="menuitem"> +<a href="../../components/spreadsheet/index.html">Overview</a> </div> - -<div class="menuItem"> -<a href="thumbnails.html">Thumbnails</a> +<div class="menuitem"> +<a href="../../components/spreadsheet/quick-guide.html">Quick Guide</a> </div> - -<div class="menuItem"> -<a href="internals.html">Internals</a> +<div class="menuitem"> +<a href="../../components/spreadsheet/how-to.html">HOWTO</a> </div> - -<div class="menuItem"> -<a href="todo.html">To Do</a> +<div class="menuitem"> +<a href="../../components/spreadsheet/converting.html">HSSF to SS Converting</a> </div> - +<div class="menuitem"> +<a href="../../components/spreadsheet/formula.html">Formula Support</a> </div> -<center> -<a href="https://www.apache.org/events/current-event.html";><img src="https://www.apache.org/events/current-event-125x125.png";></a> -</center> +<div class="menuitem"> +<a href="../../components/spreadsheet/eval.html">Formula Evaluation</a> </div> +<div class="menuitem"> +<a href="../../components/spreadsheet/eval-devguide.html">Eval Dev Guide</a> </div> -<form target="_blank" action="https://www.google.com/search"; method="get"> -<table summary="search" border="0" cellspacing="0" cellpadding="0"> -<tr> -<td><img height="1" width="1" alt="" src="../skin/images/spacer.gif" class="spacer"></td><td nowrap="nowrap"> - Search Apache POI<br> -<input value="poi.apache.org" name="sitesearch" type="hidden"><input size="10" name="q" id="query" type="text"><img height="1" width="5" alt="" src="../skin/images/spacer.gif" class="spacer"><input name="Search" value="GO" type="submit"></td><td><img height="1" width="1" alt="" src="../skin/images/spacer.gif" class="spacer"></td> -</tr> -<tr> -<td colspan="3"><img height="7" width="1" alt="" src="../skin/images/spacer.gif" class="spacer"></td> -</tr> -<tr> -<td class="bottom-left-thick"></td><td bgcolor="#a5b6c6"><img height="1" width="1" alt="" src="../skin/images/spacer.gif" class="spacer"></td><td class="bottom-right-thick"></td> -</tr> -</table> -</form> -</td> -<!--================= end Menu ==================--> -<!--================= start Content ==================--><td> -<div id="bodycol"> -<div class="app"> -<div align="center"> -<h1>HPSF HOW-TO</h1> +<div class="menuitem"> +<a href="../../components/spreadsheet/examples.html">Examples</a> </div> -<div class="h3"> - - +<div class="menuitem"> +<a href="../../components/spreadsheet/use-case.html">Use Case</a> +</div> +<div class="menuitem"> +<a href="../../components/spreadsheet/diagrams.html">Pictorial Docs</a> +</div> +<div class="menuitem"> +<a href="../../components/spreadsheet/limitations.html">Limitations</a> +</div> +<div class="menuitem"> +<a href="../../components/spreadsheet/user-defined-functions.html">User Defined Functions</a> +</div> +<div class="menuitem"> +<a href="../../components/spreadsheet/excelant.html">ExcelAnt Tests</a> +</div> +<div class="menuitem"> +<a href="../../components/spreadsheet/hacking-hssf.html">Hacking HSSF</a> +</div> +<div class="menuitem"> +<a href="../../components/spreadsheet/record-generator.html">Record Generator</a> +</div> +<div class="menuitem"> +<a href="../../components/spreadsheet/chart.html">Charts</a> +</div> +</div> +<div onclick="SwitchMenu('menu_1.1.4', '../../skin/')" id="menu_1.1.4Title" class="menutitle">PowerPoint (HSLF/XSLF)</div> +<div id="menu_1.1.4" class="menuitemgroup"> +<div class="menuitem"> +<a href="../../components/slideshow/index.html">Overview</a> +</div> +<div class="menuitem"> +<a href="../../components/slideshow/quick-guide.html">Quick Guide</a> +</div> +<div class="menuitem"> +<a href="../../components/slideshow/how-to-shapes.html">HSLF Cookbook</a> +</div> +<div class="menuitem"> +<a href="../../components/slideshow/xslf-cookbook.html">XSLF Cookbook</a> +</div> +<div class="menuitem"> +<a href="../../components/slideshow/ppt-file-format.html">PPT File Format</a> +</div> +</div> +<div onclick="SwitchMenu('menu_1.1.5', '../../skin/')" id="menu_1.1.5Title" class="menutitle">Word (HWPF/XWPF)</div> +<div id="menu_1.1.5" class="menuitemgroup"> +<div class="menuitem"> +<a href="../../components/document/index.html">Overview</a> +</div> +<div class="menuitem"> +<a href="../../components/document/quick-guide.html">HWPF Quick Guide</a> +</div> +<div class="menuitem"> +<a href="../../components/document/quick-guide-xwpf.html">XWPF Quick Guide</a> +</div> +<div class="menuitem"> +<a href="../../components/document/docoverview.html">HWPF Format</a> +</div> +<div class="menuitem"> +<a href="../../components/document/projectplan.html">HWPF Project plan</a> +</div> +</div> +<div class="menuitem"> +<a href="../../components/hsmf/index.html">Outlook (HSMF)</a> +</div> +<div class="menuitem"> +<a href="../../components/diagram/index.html">Visio (HDGF+XDGF)</a> +</div> +<div onclick="SwitchMenu('menu_1.1.8', '../../skin/')" id="menu_1.1.8Title" class="menutitle">Publisher (HPBF)</div> +<div id="menu_1.1.8" class="menuitemgroup"> +<div class="menuitem"> +<a href="../../components/hpbf/index.html">Overview</a> +</div> +<div class="menuitem"> +<a href="../../components/hpbf/file-format.html">File Format</a> +</div> +</div> +<div onclick="SwitchMenu('menu_1.1.9', '../../skin/')" id="menu_1.1.9Title" class="menutitle">OLE2 Filesystem (POIFS)</div> +<div id="menu_1.1.9" class="menuitemgroup"> +<div class="menuitem"> +<a href="../../components/poifs/index.html">Overview</a> +</div> +<div class="menuitem"> +<a href="../../components/poifs/how-to.html">How To</a> +</div> +<div class="menuitem"> +<a href="../../components/poifs/embeded.html">Embedded Documents</a> +</div> +<div class="menuitem"> +<a href="../../components/poifs/fileformat.html">File System Documentation</a> +</div> +<div class="menuitem"> +<a href="../../components/poifs/usecases.html">Use Cases</a> +</div> +<div class="menuitem"> +<a href="../../components/poifs/design.html">Design</a> +</div> +</div> +<div onclick="SwitchMenu('menu_selected_1.1.10', '../../skin/')" id="menu_selected_1.1.10Title" class="menutitle" style="background-image: url('../../skin/images/chapter_open.gif');">OLE2 Document Props (HPSF)</div> +<div id="menu_selected_1.1.10" class="selectedmenuitemgroup" style="display: block;"> +<div class="menuitem"> +<a href="../../components/hpsf/index.html">Overview</a> +</div> +<div class="menupage"> +<div class="menupagetitle">How To</div> +</div> +<div class="menuitem"> +<a href="../../components/hpsf/thumbnails.html">Thumbnails</a> +</div> +<div class="menuitem"> +<a href="../../components/hpsf/internals.html">Internals</a> +</div> +<div class="menuitem"> +<a href="../../components/hpsf/todo.html">To Do</a> +</div> +</div> +<div class="menuitem"> +<a href="../../components/hmef/index.html">TNEF (HMEF) for winmail.dat</a> +</div> +<div class="menuitem"> +<a href="../../components/oxml4j/index.html">OpenXML4J (OOXML)</a> +</div> +<div class="menuitem"> +<a href="../../components/logging.html">Logging framework</a> +</div> +</div> +<div id="credit"></div> +<div id="roundbottom"> +<img style="display: none" class="corner" height="15" width="15" alt="" src="../../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div> +<!--+ + |alternative credits + +--> +<div id="credit2"> +<a href="https://donate.apache.org/";><img border="0" title="Support Apache" alt="Support Apache - logo" src="../../images/support-asf.png" style="width: 125px;height: 125px;"></a> +</div> +</div> +<!--+ + |end Menu + +--> +<!--+ + |start content + +--> +<div id="content"> +<h1>HPSF HOW-TO</h1> +<div id="front-matter"></div> <a name="How+To+Use+the+HPSF+API"></a> -<div class="h3"> -<h3>How To Use the HPSF API<a title="Permanent link" class="headerlink" href="#How+To+Use+the+HPSF+API">#</a> -</h3> -</div> - - +<h2 class="boxed">How To Use the HPSF API</h2> +<div class="section"> <p>This HOW-TO is organized in four sections. You should read them sequentially because the later sections build upon the earlier ones.</p> - - <ol> <li> @@ -194,29 +334,17 @@ if (VERSION > 3) { </li> </ol> - - -<div class="frame note"> +<div class="note"> <div class="label">Note</div> <div class="content"> <strong>Please note:</strong> HPSF's writing functionality is <strong>not</strong> present in POI releases up to and including 2.5. In order to write properties you have to download a 3.0.x POI release, - or retrieve the POI development version from the <a href="../subversion.html">Subversion repository</a>.</div> -</div> - - - - -<a name="sec1"></a> - <a name="Reading+Standard+Properties"></a> -<div class="h4"> -<h4>Reading Standard Properties<a title="Permanent link" class="headerlink" href="#Reading+Standard+Properties">#</a> -</h4> + or retrieve the POI development version from the <a href="../../devel/subversion.html">Subversion repository</a>.</div> </div> - - -<div class="frame note"> +<a name="sec1" id="sec1"></a><a name="Reading+Standard+Properties"></a> +<h3 class="boxed">Reading Standard Properties</h3> +<div class="note"> <div class="label">Note</div> <div class="content">This section explains how to read the most important standard properties of a Microsoft Office document. Standard properties are things @@ -225,15 +353,11 @@ if (VERSION > 3) { properties. Chances are that you will find here what you need and don't have to read the other sections.</div> </div> - - <p>If all you are interested in is getting the textual content of all the document properties, such as for full text indexing, then take a look at <span class="codefrag">org.apache.poi.hpsf.extractor.HPSFPropertiesExtractor</span>. However, if you want full access to the properties, please read on!</p> - - <p>The first thing you should understand is that a Microsoft Office file is not one large bunch of bytes but has an internal filesystem structure with files and directories. You can access these files and directories using @@ -247,21 +371,15 @@ if (VERSION > 3) { filesystem is not necessarily created by or for a Microsoft Office application, because it is shorter, and because we want to avoid the name of That Redmond Company.</p> - - <p>The following example shows how to read the "title" property. Reading other properties is similar. Consider the API documentation of the class <span class="codefrag">org.apache.poi.hpsf.SummaryInformation</span> to learn which methods are available.</p> - - <p>The standard properties this section focuses on can be found in a document called <em>\005SummaryInformation</em> located in the root of the POI filesystem. The notation <em>\005</em> in the document's name means the character with a decimal value of 5. In order to read the "title" property, an application has to perform the following steps:</p> - - <ol> <li> @@ -280,27 +398,15 @@ if (VERSION > 3) { </li> </ol> - - <p>Sounds easy, doesn't it? Here are the steps in detail.</p> - - - <a name="Open+the+document+%5C005SummaryInformation+in+the+root+of+the%0A+++++++POI+filesystem"></a> -<div class="h2"> -<h2>Open the document \005SummaryInformation in the root of the - POI filesystem<a title="Permanent link" class="headerlink" href="#Open+the+document+%5C005SummaryInformation+in+the+root+of+the%0A+++++++POI+filesystem">#</a> -</h2> -</div> - - +<h4>Open the document \005SummaryInformation in the root of the + POI filesystem</h4> <p>An application that wants to open a document in a POI filesystem (POIFS) proceeds as shown by the following code fragment. The full source code of the sample application is available in the <em>examples</em> section of the POI source tree as <em>ReadTitle.java</em>.</p> - - <pre class="code"> import java.io.*; import org.apache.poi.hpsf.*; @@ -317,14 +423,8 @@ public static void main(String[] args) "\005SummaryInformation"); r.read(new FileInputStream(filename)); }</pre> - - <p>The first interesting statement is</p> - - <pre class="code">POIFSReader r = new POIFSReader();</pre> - - <p>It creates a <span class="codefrag">org.apache.poi.poifs.eventfilesystem.POIFSReader</span> instance which we shall need to read the POI filesystem. Before the application @@ -332,13 +432,9 @@ public static void main(String[] args) <span class="codefrag">POIFSReader</span> which documents we are interested in. In this case the application should do something with the document <em>\005SummaryInformation</em>.</p> - - <pre class="code"> r.registerListener(new MyPOIFSReaderListener(), "\005SummaryInformation");</pre> - - <p>This method call registers a <span class="codefrag">org.apache.poi.poifs.eventfilesystem.POIFSReaderListener</span> with the <span class="codefrag">POIFSReader</span>. The <span class="codefrag">POIFSReaderListener</span> @@ -351,20 +447,12 @@ r.registerListener(new MyPOIFSReaderList <em>\005SummaryInformation</em> document. In the sample application <span class="codefrag">MyPOIFSReaderListener</span> is a static class in the <em>ReadTitle.java</em> source file.</p> - - <p>Now everything is prepared and reading the POI filesystem can start:</p> - - <pre class="code">r.read(new FileInputStream(filename));</pre> - - <p>The following source code fragment shows the <span class="codefrag">MyPOIFSReaderListener</span> class and how it retrieves the title.</p> - - <pre class="code"> static class MyPOIFSReaderListener implements POIFSReaderListener { @@ -390,23 +478,13 @@ static class MyPOIFSReaderListener imple } } </pre> - - <p>The line</p> - - <pre class="code">SummaryInformation si = null;</pre> - - <p>declares a <span class="codefrag">SummaryInformation</span> variable and initializes it with <span class="codefrag">null</span>. We need an instance of this class to access the title. The instance is created in a <span class="codefrag">try</span> block:</p> - - <pre class="code">si = (SummaryInformation) PropertySetFactory.create(event.getStream());</pre> - - <p>The expression <span class="codefrag">event.getStream()</span> returns the input stream containing the bytes of the property set stream named <em>\005SummaryInformation</em>. This stream is passed into the @@ -416,26 +494,18 @@ static class MyPOIFSReaderListener imple less safe to cast this result to <span class="codefrag">SummaryInformation</span>, a convenience class with methods like <span class="codefrag">getTitle()</span>, <span class="codefrag">getAuthor()</span> etc.</p> - - <p>The <span class="codefrag">PropertySetFactory.create()</span> method may throw all sorts of exceptions. We'll deal with them in the next sections. For now we just catch all exceptions and throw a <span class="codefrag">RuntimeException</span> containing the message text of the origin exception.</p> - - <p>If all goes well, the sample application retrieves the title and prints it to the standard output. As you can see you must be prepared for the case that the POI filesystem does not have a title.</p> - - <pre class="code">final String title = si.getTitle(); if (title != null) System.out.println("Title: \"" + title + "\""); else System.out.println("Document has no title.");</pre> - - <p>Please note that a POI filesystem does not necessarily contain the <em>\005SummaryInformation</em> stream. The documents created by the Microsoft Office suite have one, as far as I know. However, an Excel @@ -443,28 +513,16 @@ else <em>\005SummaryInformation</em> stream. In this case the applications won't throw an exception but simply does not call the <span class="codefrag">processPOIFSReaderEvent</span> method. You have been warned!</p> - - - - -<a name="sec2"></a> - <a name="Additional+Standard+Properties%2C+Exceptions+And+Embedded%0A++++Objects"></a> -<div class="h4"> -<h4>Additional Standard Properties, Exceptions And Embedded - Objects<a title="Permanent link" class="headerlink" href="#Additional+Standard+Properties%2C+Exceptions+And+Embedded%0A++++Objects">#</a> -</h4> -</div> - - -<div class="frame note"> +<a name="sec2" id="sec2"></a><a name="Additional+Standard+Properties%2C+Exceptions+And+Embedded%0A++++Objects"></a> +<h3 class="boxed">Additional Standard Properties, Exceptions And Embedded + Objects</h3> +<div class="note"> <div class="label">Note</div> <div class="content">This section focusses on reading additional standard properties which are kept in the <strong>document summary information</strong> stream. It also talks about exceptions that may be thrown when dealing with HPSF and shows how you can read properties of embedded objects.</div> </div> - - <p>A couple of <strong>additional standard properties</strong> are not contained in the <em>\005SummaryInformation</em> stream explained above. Examples for such properties are a document's category or the @@ -473,8 +531,6 @@ else <em>\005DocumentSummaryInformation</em> to hold these properties. With two minor exceptions you can proceed exactly as described above to read the properties stored in <em>\005DocumentSummaryInformation</em>:</p> - - <ul> <li>Instead of <em>\005SummaryInformation</em> use @@ -485,21 +541,15 @@ else <span class="codefrag">DocumentSummaryInformation</span>.</li> </ul> - - <p>And of course you cannot call <span class="codefrag">getTitle()</span> because <span class="codefrag">DocumentSummaryInformation</span> has different query methods, e.g. <span class="codefrag">getCategory</span>. See the Javadoc API documentation for the details.</p> - - <p>In the previous section the application simply caught all <strong>exceptions</strong> and was in no way interested in any details. However, a real application will likely want to know what went wrong and act appropriately. Besides any I/O exceptions there are three HPSF resp. POI specific exceptions you should know about:</p> - - <dl> <dt> @@ -543,8 +593,6 @@ else different.</dd> </dl> - - <p>Many Microsoft Office documents contain <strong>embedded objects</strong>, for example an Excel sheet within a Word document. Embedded objects may have property sets of their own. An @@ -556,20 +604,9 @@ else tries to open each and every document in a POI filesystem as a property set stream. If this operation was successful it displays the properties.</p> - - - - - -<a name="sec3"></a> - <a name="Writing+Standard+Properties"></a> -<div class="h4"> -<h4>Writing Standard Properties<a title="Permanent link" class="headerlink" href="#Writing+Standard+Properties">#</a> -</h4> -</div> - - -<div class="frame note"> +<a name="sec3" id="sec3"></a><a name="Writing+Standard+Properties"></a> +<h3 class="boxed">Writing Standard Properties</h3> +<div class="note"> <div class="label">Note</div> <div class="content">This section explains how to <strong>write standard properties</strong>. HPSF provides some high-level classes and methods @@ -577,8 +614,6 @@ else low-level writing functions explained in <a href="#sec4">another section</a>.</div> </div> - - <p>As explained above, standard properties are located in the summary information and document summary information streams of typical POI filesystems. You have already learned about the classes @@ -586,13 +621,9 @@ else <span class="codefrag">DocumentSummaryInformation</span> and their <span class="codefrag">get...()</span> methods for reading standard properties. These classes also provide <span class="codefrag">set...()</span> methods for writing properties.</p> - - <p>After setting properties in <span class="codefrag">SummaryInformation</span> or <span class="codefrag">DocumentSummaryInformation</span> you have to write them to a disk file. The following sample program shows how you can</p> - - <ol> <li>read a disk file into a POI filesystem,</li> @@ -607,14 +638,10 @@ else <li>write the POI filesystem to a disk file.</li> </ol> - - <p>The complete source code of this program is available as <em>ModifyDocumentSummaryInformation.java</em> in the <em>examples</em> section of the POI source tree.</p> - - -<div class="frame note"> +<div class="note"> <div class="label">Note</div> <div class="content">Dealing with the summary information stream is analogous to handling the document summary information and therefore does not need to be @@ -622,23 +649,15 @@ else the <span class="codefrag">set...()</span> methods of the class <span class="codefrag">SummaryInformation</span>.</div> </div> - - <p>The first step is to read the POI filesystem into memory:</p> - - <pre class="code">InputStream is = new FileInputStream(poiFilesystem); POIFSFileSystem poifs = new POIFSFileSystem(is); is.close();</pre> - - <p>The code snippet above assumes that the variable <span class="codefrag">poiFilesystem</span> holds the name of a disk file. It reads the file from an input stream and creates a <span class="codefrag">POIFSFileSystem</span> object in memory. After having read the file, the input stream should be closed as shown.</p> - - <p>In order to read the document summary information stream the application must open the element <em>\005DocumentSummaryInformation</em> in the POI filesystem's root directory. However, the POI filesystem does not @@ -646,8 +665,6 @@ is.close();</pre> application should be able to deal with that situation. The following code does so by creating a new <span class="codefrag">DocumentSummaryInformation</span> if there is none in the POI filesystem:</p> - - <pre class="code">DirectoryEntry dir = poifs.getRoot(); DocumentSummaryInformation dsi; try @@ -666,14 +683,8 @@ catch (FileNotFoundException ex) dsi = PropertySetFactory.newDocumentSummaryInformation(); } </pre> - - <p>In the source code above the statement</p> - - <pre class="code">DirectoryEntry dir = poifs.getRoot();</pre> - - <p>gets hold of the POI filesystem's root directory as a <span class="codefrag">DirectoryEntry</span>. The <span class="codefrag">getEntry()</span> method of this class is used to access a file or directory entry in a directory. However, @@ -681,12 +692,8 @@ catch (FileNotFoundException ex) <span class="codefrag">FileNotFoundException</span> will be thrown. Therefore opening the document summary information entry should be done in a <span class="codefrag">try</span> block:</p> - - <pre class="code"> DocumentEntry dsiEntry = (DocumentEntry) dir.getEntry(DocumentSummaryInformation.DEFAULT_STREAM_NAME);</pre> - - <p> <span class="codefrag">DocumentSummaryInformation.DEFAULT_STREAM_NAME</span> represents the string "\005DocumentSummaryInformation", i.e. the standard name of a @@ -694,112 +701,69 @@ catch (FileNotFoundException ex) <span class="codefrag">getEntry()</span> method returns a <span class="codefrag">DocumentEntry</span>. To read the <span class="codefrag">DocumentEntry</span>'s contents, create a <span class="codefrag">DocumentInputStream</span>:</p> - - <pre class="code"> DocumentInputStream dis = new DocumentInputStream(dsiEntry);</pre> - - <p>Up to this point we have used POI's <a href="../poifs/index.html">POIFS component</a>. Now HPSF enters the stage. A property set is created from the input stream's data:</p> - - <pre class="code"> PropertySet ps = new PropertySet(dis); dis.close(); dsi = new DocumentSummaryInformation(ps); </pre> - - <p>If the data really constitutes a property set, a <span class="codefrag">PropertySet</span> object is created. Otherwise a <span class="codefrag">NoPropertySetStreamException</span> is thrown. After having read the data from the input stream the latter should be closed.</p> - - <p>Since we know - or at least hope - that the stream named "\005DocumentSummaryInformation" is not just any property set but really contains the document summary information, we try to create a new <span class="codefrag">DocumentSummaryInformation</span> from the property set. If the stream is not document summary information stream the sample application fails with a <span class="codefrag">UnexpectedPropertySetTypeException</span>.</p> - - <p>If the POI document does not contain a document summary information stream, we can create a new one in the <span class="codefrag">catch</span> clause. The <span class="codefrag">PropertySetFactory</span>'s method <span class="codefrag">newDocumentSummaryInformation()</span> establishes a new and empty <span class="codefrag">DocumentSummaryInformation</span> instance:</p> - - <pre class="code"> dsi = PropertySetFactory.newDocumentSummaryInformation();</pre> - - <p>Whether we read the document summary information from the POI filesystem or created it from scratch, in either case we now have a <span class="codefrag">DocumentSummaryInformation</span> instance we can write to. Writing is quite simple, as the following line of code shows:</p> - - <pre class="code">dsi.setCategory("POI example");</pre> - - <p>This statement sets the "category" property to "POI example". Any former "category" value will be lost. If there hasn't been a "category" property yet, a new one will be created.</p> - - <p> <span class="codefrag">DocumentSummaryInformation</span> of course has methods to set the other standard properties, too - look into the API documentation to see all of them.</p> - - <p>Once all properties are set as needed, they should be stored into the file on disk. The first step is to write the <span class="codefrag">DocumentSummaryInformation</span> into the POI filesystem:</p> - - <pre class="code">dsi.write(dir, DocumentSummaryInformation.DEFAULT_STREAM_NAME);</pre> - - <p>The <span class="codefrag">DocumentSummaryInformation</span>'s <span class="codefrag">write()</span> method takes two parameters: The first is the <span class="codefrag">DirectoryEntry</span> in the POI filesystem, the second is the name of the stream to create in the directory. If this stream already exists, it will be overwritten.</p> - - -<div class="frame note"> +<div class="note"> <div class="label">Note</div> <div class="content">If you not only modified the document summary information but also the summary information you have to write both of them to the POI filesystem.</div> </div> - - <p>Still the POI filesystem is a data structure in memory only and must be written to a disk file to make it permanent. The following lines write back the POI filesystem to the file it was read from before. Please note that in production-quality code you should never write directly to the origin file, because in case of an error everything would be lost. Here it is done this way to keep the example short.</p> - - <pre class="code">OutputStream out = new FileOutputStream(poiFilesystem); poifs.writeFilesystem(out); out.close();</pre> - - <a name="User-Defined+Properties"></a> -<div class="h2"> -<h2>User-Defined Properties<a title="Permanent link" class="headerlink" href="#User-Defined+Properties">#</a> -</h2> -</div> - - +<h4>User-Defined Properties</h4> <p>If you compare the source code excerpts above with the file containing the full source code, you will notice that I left out some following lines of code. The are dealing with the special topic of custom properties.</p> - - <pre class="code">DocumentSummaryInformation dsi = ... ... CustomProperties customProperties = dsi.getCustomProperties(); @@ -819,28 +783,20 @@ Object value = customProperties.get("Sam /* Write the custom properties back to the document summary * information. */ dsi.setCustomProperties(customProperties);</pre> - - <p>Custom properties are properties the user can define himself. Using for example Microsoft Word he can define these extra properties and give each of them a <strong>name</strong>, a <strong>type</strong> and a <strong>value</strong>. The custom properties are stored in the document information summary along with the standard properties.</p> - - <p>The source code example shows how to retrieve the custom properties as a whole from a <span class="codefrag">DocumentSummaryInformation</span> instance using the <span class="codefrag">getCustomProperties()</span> method. The result is a <span class="codefrag">CustomProperties</span> instance or <span class="codefrag">null</span> if no user-defined properties exist.</p> - - <p>Since <span class="codefrag">CustomProperties</span> implements the <span class="codefrag">Map</span> interface you can read and write properties with the usual <span class="codefrag">Map</span> methods. However, <span class="codefrag">CustomProperties</span> poses some restrictions on the types of keys and values.</p> - - <ul> <li>The <strong>key</strong> is a string.</li> @@ -850,8 +806,6 @@ dsi.setCustomProperties(customProperties <span class="codefrag">Short</span>, or <span class="codefrag">java.util.Date</span>.</li> </ul> - - <p>The <span class="codefrag">CustomProperties</span> class has been designed for easy access using just keys and values. The underlying Microsoft-specific custom properties data structure is more complicated. However, it does @@ -863,37 +817,17 @@ dsi.setCustomProperties(customProperties of those properties having the same name. You can find out whether a <span class="codefrag">CustomProperties</span> instance dropped any properties with the <span class="codefrag">isPure()</span> method.</p> - - <p>You can read and write the full spectrum of custom properties with HPSF's low-level methods. They are explained in the <a href="#sec4">next section</a>.</p> - - - - - - -<a name="sec4"></a> - <a name="Reading+Non-Standard+Properties"></a> -<div class="h4"> -<h4>Reading Non-Standard Properties<a title="Permanent link" class="headerlink" href="#Reading+Non-Standard+Properties">#</a> -</h4> -</div> - - -<div class="frame note"> +<a name="sec4" id="sec4"></a><a name="Reading+Non-Standard+Properties"></a> +<h3 class="boxed">Reading Non-Standard Properties</h3> +<div class="note"> <div class="label">Note</div> <div class="content">This section tells how to read non-standard properties. Non-standard properties are application-specific ID/type/value triples.</div> </div> - - <a name="Overview"></a> -<div class="h2"> -<h2>Overview<a title="Permanent link" class="headerlink" href="#Overview">#</a> -</h2> -</div> - +<h4>Overview</h4> <p>Now comes the real hardcode stuff. As mentioned above, <span class="codefrag">SummaryInformation</span> and <span class="codefrag">DocumentSummaryInformation</span> are just special cases of the @@ -901,8 +835,6 @@ dsi.setCustomProperties(customProperties <strong>property set</strong> consists of properties and that each <strong>property</strong> is an entity with an <strong>ID</strong>, a <strong>type</strong>, and a <strong>value</strong>.</p> - - <p>Okay, that was still rather easy. However, to make things more complicated, Microsoft in its infinite wisdom decided that a property set shalt be broken into one or more <strong>sections</strong>. Each section @@ -910,11 +842,7 @@ dsi.setCustomProperties(customProperties enough, a section may have an optional <strong>dictionary</strong> that maps property IDs to <strong>property names</strong> - we'll explain later what that means.</p> - - <p>The procedure to get to the properties is the following:</p> - - <ol> <li>Use the <strong><span class="codefrag">PropertySetFactory</span></strong> class to @@ -946,29 +874,18 @@ dsi.setCustomProperties(customProperties class has methods to retrieve them.</li> </ol> - - - -<a name="A+Sample+Application"></a> -<div class="h2"> -<h2>A Sample Application<a title="Permanent link" class="headerlink" href="#A+Sample+Application">#</a> -</h2> -</div> - +<a name="A+Sample+Application"></a> +<h4>A Sample Application</h4> <p>Let's have a look at a sample Java application that dumps all property set streams contained in a POI file system. The full source code of this program can be found as <em>ReadCustomPropertySets.java</em> in the <em>examples</em> area of the POI source code tree. Here are the key sections:</p> - - <pre class="code">import java.io.*; import java.util.*; import org.apache.poi.hpsf.*; import org.apache.poi.poifs.eventfilesystem.*; import org.apache.poi.util.HexDump;</pre> - - <p>The most important package the application needs is <span class="codefrag">org.apache.poi.hpsf.*</span>. This package contains the HPSF classes. Most classes named below are from the HPSF package. Of course we @@ -977,8 +894,6 @@ import org.apache.poi.util.HexDump;</pre we use the <span class="codefrag">List</span> and <span class="codefrag">Iterator</span> class. The class <span class="codefrag">org.apache.poi.util.HexDump</span> provides a methods to dump byte arrays as nicely formatted strings.</p> - - <pre class="code">public static void main(String[] args) throws IOException { @@ -989,24 +904,13 @@ import org.apache.poi.util.HexDump;</pre r.registerListener(new MyPOIFSReaderListener()); r.read(new FileInputStream(filename)); }</pre> - - <p>The <span class="codefrag">POIFSReader</span> is set up in a way that the listener <span class="codefrag">MyPOIFSReaderListener</span> is called on every file in the POI file system.</p> - - - <a name="The+Property+Set"></a> -<div class="h2"> -<h2>The Property Set<a title="Permanent link" class="headerlink" href="#The+Property+Set">#</a> -</h2> -</div> - +<h4>The Property Set</h4> <p>The listener class tries to create a <span class="codefrag">PropertySet</span> from each stream using the <span class="codefrag">PropertySetFactory.create()</span> method:</p> - - <pre class="code">static class MyPOIFSReaderListener implements POIFSReaderListener { public void processPOIFSReaderEvent(POIFSReaderEvent event) @@ -1032,8 +936,6 @@ import org.apache.poi.util.HexDump;</pre /* Print the name of the property set stream: */ out("Property set stream \"" + event.getPath() + event.getName() + "\":");</pre> - - <p>Creating the <span class="codefrag">PropertySet</span> is done in a <span class="codefrag">try</span> block, because not each stream in the POI file system contains a property set. If it is some other file, the @@ -1043,19 +945,10 @@ import org.apache.poi.util.HexDump;</pre other types of exceptions cause the program to terminate by throwing a runtime exception. If all went well, we can print the name of the property set stream.</p> - - - <a name="The+Sections"></a> -<div class="h2"> -<h2>The Sections<a title="Permanent link" class="headerlink" href="#The+Sections">#</a> -</h2> -</div> - +<h4>The Sections</h4> <p>The next step is to print the number of sections followed by the sections themselves:</p> - - <pre class="code">/* Print the number of sections: */ final long sectionCount = ps.getSectionCount(); out(" No. of sections: " + sectionCount); @@ -1070,22 +963,14 @@ for (Iterator i = sections.iterator(); i // See below for the complete loop body. }</pre> - - <p>The <span class="codefrag">PropertySet</span>'s method <span class="codefrag">getSectionCount()</span> returns the number of sections.</p> - - <p>To retrieve the sections, use the <span class="codefrag">getSections()</span> method. This method returns a <span class="codefrag">java.util.List</span> containing instances of the <span class="codefrag">Section</span> class in their proper order.</p> - - <p>The sample code shows a loop that retrieves the <span class="codefrag">Section</span> objects one by one and prints some information about each one. Here is the complete body of the loop:</p> - - <pre class="code">/* Print a single section: */ Section sec = (Section) i.next(); out(" Section " + nr++ + ":"); @@ -1109,15 +994,8 @@ for (int i2 = 0; i2 < properties.leng out(" Property ID: " + id + ", type: " + type + ", value: " + value); }</pre> - - - <a name="The+Section%27s+Format+ID"></a> -<div class="h2"> -<h2>The Section's Format ID<a title="Permanent link" class="headerlink" href="#The+Section%27s+Format+ID">#</a> -</h2> -</div> - +<h4>The Section's Format ID</h4> <p>The first method called on the <span class="codefrag">Section</span> instance is <span class="codefrag">getFormatID()</span>. As explained above, the format ID of the first section in a property set determines the type of the property @@ -1126,13 +1004,9 @@ for (int i2 = 0; i2 < properties.leng should have defined a unique format ID and, when reading a property set stream, should check the format ID is equal to that unique format ID. The sample program just prints the format ID it finds in a section:</p> - - <pre class="code">String s = hex(sec.getFormatID().getBytes()); s = s.substring(0, s.length() - 1); out(" Format ID: " + s);</pre> - - <p>As you can see, the <span class="codefrag">getFormatID()</span> method returns a <span class="codefrag">ClassID</span> object. An array containing the bytes can be retrieved with <span class="codefrag">ClassID.getBytes()</span>. In order to get a nicely @@ -1141,39 +1015,22 @@ out(" Format ID: " + s);</pre> the <span class="codefrag">org.apache.poi.util</span> package. Another helper method is <span class="codefrag">out()</span> which just saves typing <span class="codefrag">System.out.println()</span>.</p> - - - <a name="The+Properties"></a> -<div class="h2"> -<h2>The Properties<a title="Permanent link" class="headerlink" href="#The+Properties">#</a> -</h2> -</div> - +<h4>The Properties</h4> <p>Before getting the properties, it is possible to find out how many properties are available in the section via the <span class="codefrag">Section.getPropertyCount()</span>. The sample application uses this method to print the number of properties to the standard output:</p> - - <pre class="code">int propertyCount = sec.getPropertyCount(); out(" No. of properties: " + propertyCount);</pre> - - <p>Now its time to get to the properties themselves. You can retrieve a section's properties with the method <span class="codefrag">Section.getProperties()</span>:</p> - - <pre class="code">Property[] properties = sec.getProperties();</pre> - - <p>As you can see the result is an array of <span class="codefrag">Property</span> objects. This class has three methods to retrieve a property's ID, its type, and its value. The following code snippet shows how to call them:</p> - - <pre class="code">for (int i2 = 0; i2 < properties.length; i2++) { /* Print a single property: */ @@ -1184,23 +1041,14 @@ out(" No. of properties: " + proper out(" Property ID: " + id + ", type: " + type + ", value: " + value); }</pre> - - - <a name="Sample+Output"></a> -<div class="h2"> -<h2>Sample Output<a title="Permanent link" class="headerlink" href="#Sample+Output">#</a> -</h2> -</div> - +<h4>Sample Output</h4> <p>The output of the sample program might look like the following. It shows the summary information and the document summary information property sets of a Microsoft Word document. However, unlike the first and second section of this HOW-TO the application does not have any code which is specific to the <span class="codefrag">SummaryInformation</span> and <span class="codefrag">DocumentSummaryInformation</span> classes.</p> - - <pre class="code">Property set stream "/SummaryInformation": No. of sections: 1 Section 0: @@ -1255,11 +1103,7 @@ Property set stream "/DocumentSummaryInf No property set stream: "/WordDocument" No property set stream: "/CompObj" No property set stream: "/1Table"</pre> - - <p>There are some interesting items to note:</p> - - <ul> <li>The first property set (summary information) consists of a single @@ -1278,23 +1122,14 @@ No property set stream: "/1Table"</pre> although they slightly tend to be sorted by their IDs.</li> </ul> - - - <a name="Property+IDs"></a> -<div class="h2"> -<h2>Property IDs<a title="Permanent link" class="headerlink" href="#Property+IDs">#</a> -</h2> -</div> - +<h4>Property IDs</h4> <p>Properties in the same section are distinguished by their IDs. This is similar to variables in a programming language like Java, which are distinguished by their names. But unlike variable names, property IDs are simple integral numbers. There is another similarity, however. Just like a Java variable has a certain scope (e.g. a member variables in a class), a property ID also has its scope of validity: the section.</p> - - <p>Two property IDs in sections with different section format IDs don't have the same meaning even though their IDs might be equal. For example, ID 4 in the first (and only) section of a summary @@ -1306,8 +1141,6 @@ No property set stream: "/1Table"</pre> count. However, there is a property with an ID of 4 in the <em>second</em> section: This is a user-defined property ID - we'll get to that topic in a minute.</p> - - <p>So, how can you find out what the meaning of a certain property ID in the summary information and the document summary information property set is? The standard property sets as such don't have any hints about the @@ -1320,15 +1153,9 @@ No property set stream: "/1Table"</pre> <span class="codefrag">org.apache.poi.hpsf.wellknown</span> package defines constants for the "well-known" property IDs. For example, there is the definition</p> - - <pre class="code">public final static int PID_AUTHOR = 4;</pre> - - <p>These definitions allow you to use symbolic names instead of numbers.</p> - - <p>In order to provide support for the other way, too, - i.e. to map property IDs to property names - the class <span class="codefrag">PropertyIDMap</span> defines two static methods: @@ -1342,22 +1169,16 @@ No property set stream: "/1Table"</pre> a key to a localized string which is displayed to the user, e.g. "Author" in English or "Verfasser" in German. HPSF might provide such language-dependent ("localized") mappings in a later release.</p> - - <p>Usually you won't have to deal with those two maps. Instead you should call the <span class="codefrag">Section.getPIDString(int)</span> method. It returns the string associated with the specified property ID in the context of the <span class="codefrag">Section</span> object.</p> - - <p>Above you learned that property IDs have a meaning in the scope of a section only. However, there are two exceptions to the rule: The property IDs 0 and 1 have a fixed meaning in <strong>all</strong> sections:</p> - - <table class="ForrestTable" cellspacing="1" cellpadding="4"> -<tr class="b"> +<tr> <th colspan="1" rowspan="1">Property ID</th> <th colspan="1" rowspan="1">Meaning</th> @@ -1365,7 +1186,7 @@ No property set stream: "/1Table"</pre> </tr> -<tr class="a"> +<tr> <td colspan="1" rowspan="1">0</td> <td colspan="1" rowspan="1">The property's value is a <strong>dictionary</strong>, i.e. a @@ -1374,7 +1195,7 @@ No property set stream: "/1Table"</pre> </tr> -<tr class="b"> +<tr> <td colspan="1" rowspan="1">1</td> <td colspan="1" rowspan="1">The property's value is the number of a <strong>codepage</strong>, @@ -1387,15 +1208,8 @@ No property set stream: "/1Table"</pre> </tr> </table> - - - <a name="Property+types"></a> -<div class="h2"> -<h2>Property types<a title="Permanent link" class="headerlink" href="#Property+types">#</a> -</h2> -</div> - +<h4>Property types</h4> <p>A property is nothing without its value. It is stored in a property set stream as a sequence of bytes. You must know the property's <strong>type</strong> in order to properly interpret those bytes and @@ -1410,19 +1224,10 @@ No property set stream: "/1Table"</pre> meaning a null-terminated string of 8-bit characters, <span class="codefrag">VT_LPWSTR = 31</span> which means a null-terminated Unicode string, or <span class="codefrag">VT_BOOL = 11</span> denoting a boolean value.</p> - - <p>In most cases you won't need a property's type because HPSF does all the work for you.</p> - - - <a name="Property+values"></a> -<div class="h2"> -<h2>Property values<a title="Permanent link" class="headerlink" href="#Property+values">#</a> -</h2> -</div> - +<h4>Property values</h4> <p>When an application wants to retrieve a property's value and calls <span class="codefrag">Property.getValue()</span>, HPSF has to interpret the bytes making out the value according to the property's type. The type determines how @@ -1434,15 +1239,11 @@ No property set stream: "/1Table"</pre> HPSF has to scan the value bytes for a Unicode null character and collect everything from the beginning to that null character as a Unicode string.</p> - - <p>The good new is that HPSF does another job for you, too: It maps the variant type to an adequate Java type.</p> - - <table class="ForrestTable" cellspacing="1" cellpadding="4"> -<tr class="b"> +<tr> <th colspan="1" rowspan="1">Variant type:</th> <th colspan="1" rowspan="1">Java type:</th> @@ -1450,7 +1251,7 @@ No property set stream: "/1Table"</pre> </tr> -<tr class="a"> +<tr> <td colspan="1" rowspan="1">VT_I2</td> <td colspan="1" rowspan="1">java.lang.Integer</td> @@ -1458,7 +1259,7 @@ No property set stream: "/1Table"</pre> </tr> -<tr class="b"> +<tr> <td colspan="1" rowspan="1">VT_I4</td> <td colspan="1" rowspan="1">java.lang.Long</td> @@ -1466,7 +1267,7 @@ No property set stream: "/1Table"</pre> </tr> -<tr class="a"> +<tr> <td colspan="1" rowspan="1">VT_FILETIME</td> <td colspan="1" rowspan="1">java.util.Date</td> @@ -1474,7 +1275,7 @@ No property set stream: "/1Table"</pre> </tr> -<tr class="b"> +<tr> <td colspan="1" rowspan="1">VT_LPSTR</td> <td colspan="1" rowspan="1">java.lang.String</td> @@ -1482,7 +1283,7 @@ No property set stream: "/1Table"</pre> </tr> -<tr class="a"> +<tr> <td colspan="1" rowspan="1">VT_LPWSTR</td> <td colspan="1" rowspan="1">java.lang.String</td> @@ -1490,7 +1291,7 @@ No property set stream: "/1Table"</pre> </tr> -<tr class="b"> +<tr> <td colspan="1" rowspan="1">VT_CF</td> <td colspan="1" rowspan="1">byte[]</td> @@ -1498,7 +1299,7 @@ No property set stream: "/1Table"</pre> </tr> -<tr class="a"> +<tr> <td colspan="1" rowspan="1">VT_BOOL</td> <td colspan="1" rowspan="1">java.lang.Boolean</td> @@ -1507,14 +1308,10 @@ No property set stream: "/1Table"</pre> </table> - - <p>The bad news is that there are still a couple of variant types HPSF does not yet support. If it encounters one of these types it returns the property's value as a byte array and leaves it to be interpreted by the application.</p> - - <p>An application retrieves a property's value by calling the <span class="codefrag">Property.getValue()</span> method. This method's return type is the abstract <span class="codefrag">Object</span> class. The <span class="codefrag">getValue()</span> method @@ -1523,16 +1320,8 @@ No property set stream: "/1Table"</pre> value and returns it. Primitive types like <span class="codefrag">int</span> or <span class="codefrag">long</span> will be returned as the corresponding class, e.g. <span class="codefrag">Integer</span> or <span class="codefrag">Long</span>.</p> - - - - <a name="Dictionaries"></a> -<div class="h2"> -<h2>Dictionaries<a title="Permanent link" class="headerlink" href="#Dictionaries">#</a> -</h2> -</div> - +<h4>Dictionaries</h4> <p>The property with ID 0 has a very special meaning: It is a <strong>dictionary</strong> mapping property IDs to property names. We have seen already that the meanings of standard properties in the @@ -1542,29 +1331,17 @@ No property set stream: "/1Table"</pre> property set. However, a user can define custom fields in, say, Microsoft Word. For each field the user has to specify a name, a type, and a value.</p> - - <p>The names of the custom-defined fields (i.e. the property names) are stored in the document summary information second section's <strong>dictionary</strong>. The dictionary is a map which associates property IDs with property names.</p> - - <p>The method <span class="codefrag">Section.getPIDString(int)</span> not only returns with the well-known property names of the summary information and document summary information property sets, but with self-defined properties, too. It should also work with self-defined properties in self-defined sections.</p> - - - <a name="Codepage+support"></a> -<div class="h2"> -<h2>Codepage support<a title="Permanent link" class="headerlink" href="#Codepage+support">#</a> -</h2> -</div> - - +<h4>Codepage support</h4> <p>The property with ID 1 holds the number of the codepage which was used to encode the strings in this section. If this property is not available in a section, the platform's default character encoding will be @@ -1572,8 +1349,6 @@ No property set stream: "/1Table"</pre> on a platform with the same default character encoding. However, if you receive a document from another region of the world and the codepage is undefined, you are in trouble.</p> - - <p>HPSF's codepage support is only as good as the character encoding support of the Java Virtual Machine (JVM) the application runs on. If HPSF encounters a codepage number it assumes that the JVM has a character @@ -1585,14 +1360,10 @@ No property set stream: "/1Table"</pre> versions since 1.4. However, under J2SE 1.3 or lower you are out of luck. You should install a newer J2SE version to process codepages with HPSF.</p> - - <p>There are some exceptions to the rule saying that a character encoding's name is derived from the codepage number by prepending the string "cp" to it. In these cases the codepage number is mapped to a well-known character encoding name. Here are a few examples:</p> - - <dl> <dt>Codepage 932</dt> @@ -1608,39 +1379,19 @@ No property set stream: "/1Table"</pre> <dd>is mapped to the character encoding "UTF-8".</dd> </dl> - - <p>More of these mappings between codepage and character encoding name are hard-coded in the classes <span class="codefrag">org.apache.poi.hpsf.Constants</span> and <span class="codefrag">org.apache.poi.hpsf.VariantSupport</span>. Probably there will be a need to add more mappings. The HPSF author will appreciate any hints.</p> - - - - -<a name="sec5"></a> - <a name="Writing+Properties"></a> -<div class="h4"> -<h4>Writing Properties<a title="Permanent link" class="headerlink" href="#Writing+Properties">#</a> -</h4> -</div> - - -<div class="frame note"> +<a name="sec5" id="sec5"></a><a name="Writing+Properties"></a> +<h3 class="boxed">Writing Properties</h3> +<div class="note"> <div class="label">Note</div> <div class="content">This section describes how to write properties.</div> </div> - - <a name="Overview+of+Writing+Properties"></a> -<div class="h2"> -<h2>Overview of Writing Properties<a title="Permanent link" class="headerlink" href="#Overview+of+Writing+Properties">#</a> -</h2> -</div> - +<h4>Overview of Writing Properties</h4> <p>Writing properties is possible at a high level and at a low level:</p> - - <ul> @@ -1655,25 +1406,13 @@ No property set stream: "/1Table"</pre> functions.</li> </ul> - - <p>HPSF's writing capabilities come with the classes <span class="codefrag">PropertySet</span>, <span class="codefrag">Section</span>, <span class="codefrag">Property</span>, and some helper classes.</p> - - - - <a name="Low-Level+Writing%3A+An+Overview"></a> -<div class="h2"> -<h2>Low-Level Writing: An Overview<a title="Permanent link" class="headerlink" href="#Low-Level+Writing%3A+An+Overview">#</a> -</h2> -</div> - +<h4>Low-Level Writing: An Overview</h4> <p>When you are going to write a property set stream your application has to perform the following steps:</p> - - <ol> <li>Create a <span class="codefrag">PropertySet</span> instance.</li> @@ -1703,15 +1442,8 @@ No property set stream: "/1Table"</pre> document.</li> </ol> - - - <a name="Low-level+Writing+Functions+In+Details"></a> -<div class="h2"> -<h2>Low-level Writing Functions In Details<a title="Permanent link" class="headerlink" href="#Low-level+Writing+Functions+In+Details">#</a> -</h2> -</div> - +<h4>Low-level Writing Functions In Details</h4> <p>Writing properties is introduced by an artificial but simple example: a program creating a new document (aka POI file system) which contains only a single document: a summary information property set stream. The latter @@ -1721,17 +1453,11 @@ No property set stream: "/1Table"</pre> use. However, it is perfectly fine for an example because it make it very simple and easy to understand, and you will get used to writing properties in real applications quickly.</p> - - <p>The application expects the name of the POI file system to be written on the command line. The title property it writes is "Sample title".</p> - - <p>Here's the application's source code. You can also find it in the "examples" section of the POI source code distribution. Explanations are following below.</p> - - <pre class="code">package org.apache.poi.hpsf.examples; import java.io.FileOutputStream; @@ -1822,15 +1548,11 @@ public class WriteTitle } }</pre> - - <p>The application first checks that there is exactly one single argument on the command line: the name of the file to write. If this single argument is present, the application stores it in the <span class="codefrag">fileName</span> variable. It will be used in the end when the POI file system is written to a disk file.</p> - - <pre class="code">if (args.length != 1) { System.err.println("Usage: " + WriteTitle.class.getName() + @@ -1838,51 +1560,31 @@ public class WriteTitle System.exit(1); } final String fileName = args[0];</pre> - - <p>Let's create a property set now. We cannot use the <span class="codefrag">PropertySet</span> class, because it is read-only. It does not have a constructor creating an empty property set, and it does not have any methods to modify its contents, i.e. to write sections containing properties into it.</p> - - <p>The class to use is <span class="codefrag">PropertySet</span>. The sample application calls its no-args constructor in order to establish an empty property set:</p> - - <pre class="code">final PropertySet mps = new PropertySet();</pre> - - <p>As said, we have an empty property set now. Later we will put some contents into it.</p> - - <p>The <span class="codefrag">PropertySet</span> created by the no-args constructor is not really empty: It contains a single section without properties. We can either retrieve that section and fill it with properties or we can replace it by another section. We can also add further sections to the property set. The sample application decides to retrieve the section being already there:</p> - - <pre class="code">final Section ms = mps.getSections().get(0);</pre> - - <p>The <span class="codefrag">getSections()</span> method returns the property set's sections as a list, i.e. an instance of <span class="codefrag">java.util.List</span>. Calling <span class="codefrag">get(0)</span> returns the list's first (or zeroth, if you prefer) element.</p> - - <p>The alternative to retrieving the <span class="codefrag">Section</span> being already there would have been to create an new <span class="codefrag">Section</span> like this:</p> - - <pre class="code">Section s = new Section();</pre> - - <p>The <span class="codefrag">Section</span> the sample application retrieved from the <span class="codefrag">PropertySet</span> is still empty. It contains no properties and does not have a format ID. As you have read <a href="#sec3">above</a> the format ID of the first section in a @@ -1894,134 +1596,79 @@ final String fileName = args[0];</pre> constant <span class="codefrag">SectionIDMap.SUMMARY_INFORMATION_ID</span>. The sample application writes it to the section using the <span class="codefrag">setFormatID(byte[])</span> method:</p> - - <pre class="code">ms.setFormatID(SectionIDMap.SUMMARY_INFORMATION_ID);</pre> - - <pre class="code">final Property p = new Property();</pre> - - <p>A <span class="codefrag">Property</span> object must have an ID, a type, and a value (see <a href="#sec3">above</a> for details). The class provides methods to set these attributes:</p> - - <pre class="code">p.setID(PropertyIDMap.PID_TITLE); p.setType(Variant.VT_LPWSTR); p.setValue("Sample title");</pre> - - <p>The <span class="codefrag">Property</span> class has a constructor which you can use to pass in all three attributes in a single call. See the Javadoc API documentation for details!</p> - - <p>The sample property set is complete now. We have a <span class="codefrag">PropertySet</span> containing a <span class="codefrag">Section</span> containing a <span class="codefrag">Property</span>. Of course we could have added more sections to the property set and more properties to the sections but we wanted to keep things simple.</p> - - <p>The property set has to be written to a POI file system. The following statement creates it.</p> - - <pre class="code">final POIFSFileSystem poiFs = new POIFSFileSystem();</pre> - - <p>Writing the property set includes the step of converting it into a sequence of bytes. The <span class="codefrag">PropertySet</span> class has the method <span class="codefrag">toInputStream()</span> for this purpose. It returns the bytes making out the property set stream as an <span class="codefrag">InputStream</span>:</p> - - <pre class="code">final InputStream is = mps.toInputStream();</pre> - - <p>If you'd read from this input stream you'd receive all the property set's bytes. However, it is very likely that you'll never do that. Instead you'll pass the input stream to the <span class="codefrag">POIFSFileSystem.createDocument()</span> method, like this:</p> - - <pre class="code">poiFs.createDocument(is, SummaryInformation.DEFAULT_STREAM_NAME);</pre> - - <p>Besides the <span class="codefrag">InputStream</span> <span class="codefrag">createDocument()</span> takes a second parameter: the name of the document to be created. For a SummaryInformation property set stream the default name is available as the constant <span class="codefrag">SummaryInformation.DEFAULT_STREAM_NAME</span>.</p> - - <p>The last step is to write the POI file system to a disk file:</p> - - <pre class="code">poiFs.writeFilesystem(new FileOutputStream(fileName));</pre> - - - - - - <a name="Further+Reading"></a> -<div class="h4"> -<h4>Further Reading<a title="Permanent link" class="headerlink" href="#Further+Reading">#</a> -</h4> -</div> - +<h3 class="boxed">Further Reading</h3> <p>There are still some aspects of HSPF left which are not covered by this HOW-TO. You should dig into the Javadoc API documentation to learn further details. Since you've struggled through this document up to this point, you are well prepared.</p> - - - - - -<div id="authors" align="right">by Rainer Klute</div> -</div> </div> + +<p align="right"> +<font size="-2">by Rainer Klute</font> +</p> +</div> +<!--+ + |end content + +--> +<div class="clearboth"> </div> </div> -</td> -<!--================= end Content ==================--> -</tr> -</tbody> -</table> -<!--================= end Main ==================--> -<!--================= start Footer ==================--> <div id="footer"> -<table summary="footer" cellspacing="0" cellpadding="4" width="100%" border="0"> -<tbody> -<tr> -<!--================= start Copyright ==================--> -<td colspan="2"> -<div align="center"> -<div class="copyright"> - Copyright © 2002-2018 The Apache Software Foundation. All rights reserved.<br> - Apache, Apache POI, and the Apache POI logo are registered trademarks or - trademarks of The Apache Software Foundation in the U.S. and/or other countries. - </div> +<!--+ + |start bottomstrip + +--> +<div class="lastmodified"> +<script type="text/javascript"><!-- +document.write("Last Published: " + document.lastModified); +// --></script> </div> -</td> -<!--================= end Copyright ==================--> -</tr> -<tr> -<td align="left"> -<!--================= start Host ==================--> -<!--================= end Host ==================--></td><td align="right"> -<!--================= start Credits ==================--> -<div align="right"> -<div class="credit"></div> +<div class="copyright"> + Copyright © + 2001-2018 <a href="https://www.apache.org/";>The Apache Software Foundation</a> </div> -<!--================= end Credits ==================--> -</td> -</tr> -</tbody> -</table> +<div id="feedback"> + Send feedback about the website to: + <a id="feedbackto" href="mailto:[email protected]?subject=Feedback%C2%A0components/hpsf/how-to.html";>[email protected]</a> +</div> +<!--+ + |end bottomstrip + +--> </div> -<!--================= end Footer ==================--> </body> </html>
--------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
![https://www.apache.org/events/current-event-125x125.png"](https://www.apache.org/events/current-event-125x125.png"){kind=link}