1    /* ====================================================================
2     * The Apache Software License, Version 1.1
3     *
4     * Copyright (c) 2000 The Apache Software Foundation.  All rights
5     * reserved.
6     *
7     * Redistribution and use in source and binary forms, with or without
8     * modification, are permitted provided that the following conditions
9     * are met:
10    *
11    * 1. Redistributions of source code must retain the above copyright
12    *    notice, this list of conditions and the following disclaimer.
13    *
14    * 2. Redistributions in binary form must reproduce the above copyright
15    *    notice, this list of conditions and the following disclaimer in
16    *    the documentation and/or other materials provided with the
17    *    distribution.
18    *
19    * 3. The end-user documentation included with the redistribution,
20    *    if any, must include the following acknowledgment:
21    *       "This product includes software developed by the
22    *        Apache Software Foundation (http://www.apache.org/)."
23    *    Alternately, this acknowledgment may appear in the software itself,
24    *    if and wherever such third-party acknowledgments normally appear.
25    *
26    * 4. The names "Apache" and "Apache Software Foundation" must
27    *    not be used to endorse or promote products derived from this
28    *    software without prior written permission. For written
29    *    permission, please contact apache@apache.org.
30    *
31    * 5. Products derived from this software may not be called "Apache",
32    *    nor may "Apache" appear in their name, without prior written
33    *    permission of the Apache Software Foundation.
34    *
35    * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
36    * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
37    * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
38    * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
39    * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
40    * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
41    * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
42    * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
43    * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
44    * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
45    * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
46    * SUCH DAMAGE.
47    * ====================================================================
48    *
49    * This software consists of voluntary contributions made by many
50    * individuals on behalf of the Apache Software Foundation.  For more
51    * information on the Apache Software Foundation, please see
52    * <http://www.apache.org/>.
53    */
54   
55   package org.apache.poi.hpsf.wellknown;
56   
57   import java.util.*;
58   
59   /**
60    * <p>Maps section format IDs to {@link PropertyIDMap}s. It is
61    * initialized with two well-known section format IDs: those of the
62    * <tt>\005SummaryInformation</tt> stream and the
63    * <tt>\005DocumentSummaryInformation stream.</p>
64    *
65    * <p>If you have a section format ID you can use it as a key to query
66    * this map. If you get a {@link PropertyIDMap} returned your section
67    * is well-known and you can query the {@link PropertyIDMap} for PID
68    * strings. If you get back <code>null</code> you are on your own.</p>
69    *
70    * <p>This {@link Map} expects the byte arrays of section format IDs
71    * as keys. A key maps to a {@link PropertyIDMap} describing the
72    * property IDs in sections with the specified section format ID.</p>
73    *
74    * @author Rainer Klute (klute@rainer-klute.de)
75    * @version $Id: SectionIDMap.java,v 1.3 2002/05/01 09:31:52 klute Exp $
76    * @since 2002-02-09
77    */
78   public class SectionIDMap extends HashMap
79   {
80   
81       /**
82        * <p>The SummaryInformation's section's format ID.</p>
83        */
84       public final static byte[] SUMMARY_INFORMATION_ID =
85           new byte[]{(byte) 0xF2, (byte) 0x9F, (byte) 0x85, (byte) 0xE0,
86                      (byte) 0x4F, (byte) 0xF9, (byte) 0x10, (byte) 0x68,
87                      (byte) 0xAB, (byte) 0x91, (byte) 0x08, (byte) 0x00,
88                      (byte) 0x2B, (byte) 0x27, (byte) 0xB3, (byte) 0xD9};
89   
90       /**
91        * <p>The DocumentSummaryInformation's first section's format
92        * ID. The second section has a different format ID which is not
93        * well-known.</p>
94        */
95       public final static byte[] DOCUMENT_SUMMARY_INFORMATION_ID =
96           new byte[]{(byte) 0xD5, (byte) 0xCD, (byte) 0xD5, (byte) 0x02,
97                      (byte) 0x2E, (byte) 0x9C, (byte) 0x10, (byte) 0x1B,
98                      (byte) 0x93, (byte) 0x97, (byte) 0x08, (byte) 0x00,
99                      (byte) 0x2B, (byte) 0x2C, (byte) 0xF9, (byte) 0xAE};
100  
101      public final static String UNDEFINED = "[undefined]";
102  
103  
104  
105      private static SectionIDMap defaultMap;
106  
107  
108  
109      /**
110       * <p>Returns the singleton instance of the default {@link
111       * SectionIDMap}.</p>
112       */
113      public static SectionIDMap getInstance()
114      {
115          if (defaultMap == null)
116          {
117              final SectionIDMap m = new SectionIDMap();
118              m.put(SUMMARY_INFORMATION_ID,
119                    PropertyIDMap.getSummaryInformationProperties());
120              m.put(DOCUMENT_SUMMARY_INFORMATION_ID,
121                    PropertyIDMap.getDocumentSummaryInformationProperties());
122              defaultMap = m;
123          }
124          return defaultMap;
125      }
126  
127  
128  
129      /**
130       * <p>Returns the property ID string that is associated with a
131       * given property ID in a section format ID's namespace.</p>
132       *
133       * @param sectionFormatID Each section format ID has its own name
134       * space of property ID strings and thus must be specified.
135       *
136       * @param pid The property ID
137       *
138       * @return The well-known property ID string associated with the
139       * property ID <var>pid</var> in the name space spanned by
140       * <var>sectionFormatID</var>. If the
141       * <var>pid</var>/<var>sectionFormatID</var> combination is not
142       * well-known, the string "[undefined]" is returned.
143       */
144      public static String getPIDString(final byte[] sectionFormatID,
145                                        final int pid)
146      {
147          final PropertyIDMap m =
148              (PropertyIDMap) getInstance().get(sectionFormatID);
149          if (m == null)
150              return UNDEFINED;
151          else
152          {
153              final String s = (String) m.get(pid);
154              if (s == null)
155                  return UNDEFINED;
156              return s;
157          }
158      }
159  
160  
161  
162      /**
163       * <p>Returns the {@link PropertyIDMap} for a given section format
164       * ID.</p>
165       */
166      public PropertyIDMap get(final byte[] sectionFormatID)
167      {
168          return (PropertyIDMap) super.get(new String(sectionFormatID));
169      }
170  
171  
172  
173      /**
174       * <p>Returns the {@link PropertyIDMap} for a given section format
175       * ID.</p>
176       *
177       * @param sectionFormatID A section format ID as a
178       * <tt>byte[]</tt>.
179       *
180       * @deprecated Use {@link #get(byte[])} instead!
181       */
182      public Object get(final Object sectionFormatID)
183      {
184          return get((byte[]) sectionFormatID);
185      }
186  
187  
188  
189      /**
190       * <p>Associates a section format ID with a {@link
191       * PropertyIDMap}.</p>
192       */
193      public Object put(final byte[] sectionFormatID,
194                        final PropertyIDMap propertyIDMap)
195      {
196          return super.put(new String(sectionFormatID), propertyIDMap);
197      }
198  
199  
200  
201      /**
202       * @deprecated Use {@link #put(byte[], PropertyIDMap)} instead!
203       */
204      public Object put(final Object key, final Object value)
205      {
206          return put((byte[]) key, (PropertyIDMap) value);
207      }
208  
209  }
210