1    /*
2     *  ====================================================================
3     *  The Apache Software License, Version 1.1
4     *
5     *  Copyright (c) 2000 The Apache Software Foundation.  All rights
6     *  reserved.
7     *
8     *  Redistribution and use in source and binary forms, with or without
9     *  modification, are permitted provided that the following conditions
10    *  are met:
11    *
12    *  1. Redistributions of source code must retain the above copyright
13    *  notice, this list of conditions and the following disclaimer.
14    *
15    *  2. Redistributions in binary form must reproduce the above copyright
16    *  notice, this list of conditions and the following disclaimer in
17    *  the documentation and/or other materials provided with the
18    *  distribution.
19    *
20    *  3. The end-user documentation included with the redistribution,
21    *  if any, must include the following acknowledgment:
22    *  "This product includes software developed by the
23    *  Apache Software Foundation (http://www.apache.org/)."
24    *  Alternately, this acknowledgment may appear in the software itself,
25    *  if and wherever such third-party acknowledgments normally appear.
26    *
27    *  4. The names "Apache" and "Apache Software Foundation" must
28    *  not be used to endorse or promote products derived from this
29    *  software without prior written permission. For written
30    *  permission, please contact apache@apache.org.
31    *
32    *  5. Products derived from this software may not be called "Apache",
33    *  nor may "Apache" appear in their name, without prior written
34    *  permission of the Apache Software Foundation.
35    *
36    *  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
37    *  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
38    *  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
39    *  DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
40    *  ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
41    *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
42    *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
43    *  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
44    *  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
45    *  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
46    *  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
47    *  SUCH DAMAGE.
48    *  ====================================================================
49    *
50    *  This software consists of voluntary contributions made by many
51    *  individuals on behalf of the Apache Software Foundation.  For more
52    *  information on the Apache Software Foundation, please see
53    *  <http://www.apache.org/>.
54    *
55    *  Portions of this software are based upon public domain software
56    *  originally written at the National Center for Supercomputing Applications,
57    *  University of Illinois, Urbana-Champaign.
58    */
59   package org.apache.poi.hpsf;
60   
61   import java.io.*;
62   import java.util.*;
63   import org.apache.poi.hpsf.wellknown.*;
64   
65   /**
66    * <p>Convenience class representing a Summary Information stream in a
67    * Microsoft Office document.</p>
68    *
69    * <p>See <a
70    * href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/com/stgu_8910.asp">http://msdn.microsoft.com/library/default.asp?url=/library/en-us/com/stgu_8910.asp</a>
71    * for documentation from That Redmond Company.</p>
72    *
73    * @author Rainer Klute (klute@rainer-klute.de)
74    * @see DocumentSummaryInformation
75    * @version $Id: SummaryInformation.java,v 1.9 2003/02/01 13:28:28 klute Exp $
76    * @since 2002-02-09
77    */
78   public class SummaryInformation extends SpecialPropertySet
79   {
80   
81       /**
82        * <p>Creates a {@link SummaryInformation} from a given {@link
83        * PropertySet}.</p>
84        *
85        * @param ps A property set which should be created from a summary
86        * information stream.
87        * @throws UnexpectedPropertySetTypeException if <var>ps</var>
88        * does not contain a summary information stream.
89        */
90       public SummaryInformation(final PropertySet ps)
91   	throws UnexpectedPropertySetTypeException
92       {
93           super(ps);
94           if (!isSummaryInformation())
95               throw new UnexpectedPropertySetTypeException
96   		("Not a " + getClass().getName());
97       }
98   
99   
100  
101      /**
102       * <p>Returns the stream's title (or <code>null</code>).</p>
103       *
104       * @return The title or <code>null</code>
105       */
106      public String getTitle()
107      {
108          return (String) getProperty(PropertyIDMap.PID_TITLE);
109      }
110  
111  
112  
113      /**
114       * <p>Returns the stream's subject (or <code>null</code>).</p>
115       *
116       * @return The subject or <code>null</code>
117       */
118      public String getSubject()
119      {
120          return (String) getProperty(PropertyIDMap.PID_SUBJECT);
121      }
122  
123  
124  
125      /**
126       * <p>Returns the stream's author (or <code>null</code>).</p>
127       *
128       * @return The author or <code>null</code>
129       */
130      public String getAuthor()
131      {
132          return (String) getProperty(PropertyIDMap.PID_AUTHOR);
133      }
134  
135  
136  
137      /**
138       * <p>Returns the stream's keywords (or <code>null</code>).</p>
139       *
140       * @return The keywords or <code>null</code>
141       */
142      public String getKeywords()
143      {
144          return (String) getProperty(PropertyIDMap.PID_KEYWORDS);
145      }
146  
147  
148  
149      /**
150       * <p>Returns the stream's comments (or <code>null</code>).</p>
151       *
152       * @return The comments or <code>null</code>
153       */
154      public String getComments()
155      {
156          return (String) getProperty(PropertyIDMap.PID_COMMENTS);
157      }
158  
159  
160  
161      /**
162       * <p>Returns the stream's template (or <code>null</code>).</p>
163       *
164       * @return The template or <code>null</code>
165       */
166      public String getTemplate()
167      {
168          return (String) getProperty(PropertyIDMap.PID_TEMPLATE);
169      }
170  
171  
172  
173      /**
174       * <p>Returns the stream's last author (or <code>null</code>).</p>
175       *
176       * @return The last author or <code>null</code>
177       */
178      public String getLastAuthor()
179      {
180          return (String) getProperty(PropertyIDMap.PID_LASTAUTHOR);
181      }
182  
183  
184  
185      /**
186       * <p>Returns the stream's revision number (or
187       * <code>null</code>). </p>
188       *
189       * @return The revision number or <code>null</code>
190       */
191      public String getRevNumber()
192      {
193          return (String) getProperty(PropertyIDMap.PID_REVNUMBER);
194      }
195  
196  
197  
198      /**
199       * <p>Returns the stream's edit time (or <code>null</code>).</p>
200       *
201       * @return The edit time or <code>null</code>
202       */
203      public Date getEditTime()
204      {
205          return (Date) getProperty(PropertyIDMap.PID_EDITTIME);
206      }
207  
208  
209  
210      /**
211       * <p>Returns the stream's last printed time (or
212       * <code>null</code>).</p>
213       *
214       * @return The last printed time or <code>null</code>
215       */
216      public Date getLastPrinted()
217      {
218          return (Date) getProperty(PropertyIDMap.PID_LASTPRINTED);
219      }
220  
221  
222  
223      /**
224       * <p>Returns the stream's creation time (or
225       * <code>null</code>).</p>
226       *
227       * @return The creation time or <code>null</code>
228       */
229      public Date getCreateDateTime()
230      {
231          return (Date) getProperty(PropertyIDMap.PID_CREATE_DTM);
232      }
233  
234  
235  
236      /**
237       * <p>Returns the stream's last save time (or
238       * <code>null</code>).</p>
239       *
240       * @return The last save time or <code>null</code>
241       */
242      public Date getLastSaveDateTime()
243      {
244          return (Date) getProperty(PropertyIDMap.PID_LASTSAVE_DTM);
245      }
246  
247  
248  
249      /**
250       * <p>Returns the stream's page count or 0 if the {@link
251       * SummaryInformation} does not contain a page count.</p>
252       *
253       * @return The page count or <code>null</code>
254       */
255      public int getPageCount()
256      {
257          return getPropertyIntValue(PropertyIDMap.PID_PAGECOUNT);
258      }
259  
260  
261  
262      /**
263       * <p>Returns the stream's word count or 0 if the {@link
264       * SummaryInformation} does not contain a word count.</p>
265       *
266       * @return The word count or <code>null</code>
267       */
268      public int getWordCount()
269      {
270          return getPropertyIntValue(PropertyIDMap.PID_WORDCOUNT);
271      }
272  
273  
274  
275      /**
276       * <p>Returns the stream's character count or 0 if the {@link
277       * SummaryInformation} does not contain a char count.</p>
278       *
279       * @return The character count or <code>null</code>
280       */
281      public int getCharCount()
282      {
283          return getPropertyIntValue(PropertyIDMap.PID_CHARCOUNT);
284      }
285  
286  
287  
288      /**
289       * <p>Returns the stream's thumbnail (or <code>null</code>)
290       * <strong>when this method is implemented. Please note that the
291       * return type is likely to change!</strong></p>
292       *
293       * <p><strong>FIXME / Hint to developers:</strong> Drew Varner
294       * <Drew.Varner -at- sc.edu> said that this is an image in
295       * WMF or Clipboard (BMP?) format. He also provided two links that
296       * might be helpful: <a
297       * href="http://www.csn.ul.ie/~caolan/publink/file/OLE2SummaryAgainst_file-3.27.patch"
298       * target="_blank">http://www.csn.ul.ie/~caolan/publink/file/OLE2SummaryAgainst_file-3.27.patch
299       * </a> and <a
300       * href="http://msdn.microsoft.com/library/en-us/dno97ta/html/msdn_docprop.asp"
301       * target="_blank">http://msdn.microsoft.com/library/en-us/dno97ta/html/msdn_docprop.asp
302       * </a>. However, we won't do any conversion into any image type
303       * but instead just return a byte array.</p>
304       *
305       * @return The thumbnail or <code>null</code>
306       */
307      public byte[] getThumbnail()
308      {
309          return (byte[]) getProperty(PropertyIDMap.PID_THUMBNAIL);
310      }
311  
312  
313  
314      /**
315       * <p>Returns the stream's application name (or
316       * <code>null</code>).</p>
317       *
318       * @return The application name or <code>null</code>
319       */
320      public String getApplicationName()
321      {
322          return (String) getProperty(PropertyIDMap.PID_APPNAME);
323      }
324  
325  
326  
327      /**
328       * <p>Returns a security code which is one of the following
329       * values:</p>
330       *
331       * <ul>
332       *  <li>
333       *   <p>0 if the {@link SummaryInformation} does not contain a
334       *   security field or if there is no security on the
335       *   document. Use {@link #wasNull} to distinguish between the
336       *   two cases!</p>
337       *  </li>
338       *
339       *  <li>
340       *   <p>1 if the document is password protected</p>
341       *  </li>
342       *
343       *   <li>
344       *    <p>2 if the document is read-only recommended</p>
345       *   </li>
346       *
347       *   <li>
348       *    <p>4 if the document is read-only enforced</p>
349       *   </li>
350       *
351       *   <li>
352       *    <p>8 if the document is locked for annotations</p>
353       *   </li>
354       *
355       * </ul>
356       *
357       * @return The security code or <code>null</code>
358       */
359      public int getSecurity()
360      {
361          return getPropertyIntValue(PropertyIDMap.PID_SECURITY);
362      }
363  
364  }
365