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   package org.apache.poi.hpsf.wellknown;
56   
57   import java.util.*;
58   
59   /**
60    *  <p>
61    *
62    *  Maps section format IDs to {@link PropertyIDMap}s. It is initialized with
63    *  two well-known section format IDs: those of the <tt>\005SummaryInformation
64    *  </tt> stream and the <tt>\005DocumentSummaryInformation stream.</p> <p>
65    *
66    *  If you have a section format ID you can use it as a key to query this map.
67    *  If you get a {@link PropertyIDMap} returned your section is well-known and
68    *  you can query the {@link PropertyIDMap} for PID strings. If you get back
69    *  <code>null</code> you are on your own.</p> <p>
70    *
71    *  This {@link Map} expects the byte arrays of section format IDs as keys. A
72    *  key maps to a {@link PropertyIDMap} describing the property IDs in sections
73    *  with the specified section format ID.</p>
74    *
75    *@author     Rainer Klute (klute@rainer-klute.de)
76    *@created    May 10, 2002
77    *@version    $Id: SectionIDMap.java,v 1.4 2002/05/11 14:47:24 acoliver Exp $
78    *@since      2002-02-09
79    */
80   public class SectionIDMap extends HashMap {
81   
82       /**
83        *  <p>
84        *
85        *  The SummaryInformation's section's format ID.</p>
86        */
87       public final static byte[] SUMMARY_INFORMATION_ID =
88               new byte[]{(byte) 0xF2, (byte) 0x9F, (byte) 0x85, (byte) 0xE0,
89               (byte) 0x4F, (byte) 0xF9, (byte) 0x10, (byte) 0x68,
90               (byte) 0xAB, (byte) 0x91, (byte) 0x08, (byte) 0x00,
91               (byte) 0x2B, (byte) 0x27, (byte) 0xB3, (byte) 0xD9};
92   
93       /**
94        *  <p>
95        *
96        *  The DocumentSummaryInformation's first section's format ID. The second
97        *  section has a different format ID which is not well-known.</p>
98        */
99       public final static byte[] DOCUMENT_SUMMARY_INFORMATION_ID =
100              new byte[]{(byte) 0xD5, (byte) 0xCD, (byte) 0xD5, (byte) 0x02,
101              (byte) 0x2E, (byte) 0x9C, (byte) 0x10, (byte) 0x1B,
102              (byte) 0x93, (byte) 0x97, (byte) 0x08, (byte) 0x00,
103              (byte) 0x2B, (byte) 0x2C, (byte) 0xF9, (byte) 0xAE};
104  
105      /**
106       *  Description of the Field
107       */
108      public final static String UNDEFINED = "[undefined]";
109  
110      private static SectionIDMap defaultMap;
111  
112  
113  
114      /**
115       *  <p>
116       *
117       *  Returns the singleton instance of the default {@link SectionIDMap}.</p>
118       *
119       *@return    The instance value
120       */
121      public static SectionIDMap getInstance() {
122          if (defaultMap == null) {
123              final SectionIDMap m = new SectionIDMap();
124              m.put(SUMMARY_INFORMATION_ID,
125                      PropertyIDMap.getSummaryInformationProperties());
126              m.put(DOCUMENT_SUMMARY_INFORMATION_ID,
127                      PropertyIDMap.getDocumentSummaryInformationProperties());
128              defaultMap = m;
129          }
130          return defaultMap;
131      }
132  
133  
134  
135      /**
136       *  <p>
137       *
138       *  Returns the property ID string that is associated with a given property
139       *  ID in a section format ID's namespace.</p>
140       *
141       *@param  sectionFormatID  Each section format ID has its own name space of
142       *      property ID strings and thus must be specified.
143       *@param  pid              The property ID
144       *@return                  The well-known property ID string associated with
145       *      the property ID <var>pid</var> in the name space spanned by <var>
146       *      sectionFormatID</var> . If the <var>pid</var> /<var>sectionFormatID
147       *      </var> combination is not well-known, the string "[undefined]" is
148       *      returned.
149       */
150      public static String getPIDString(final byte[] sectionFormatID,
151              final int pid) {
152          final PropertyIDMap m =
153                  (PropertyIDMap) getInstance().get(sectionFormatID);
154          if (m == null) {
155              return UNDEFINED;
156          } else {
157              final String s = (String) m.get(pid);
158              if (s == null) {
159                  return UNDEFINED;
160              }
161              return s;
162          }
163      }
164  
165  
166  
167      /**
168       *  <p>
169       *
170       *  Returns the {@link PropertyIDMap} for a given section format ID.</p>
171       *
172       *@param  sectionFormatID  Description of the Parameter
173       *@return                  Description of the Return Value
174       */
175      public PropertyIDMap get(final byte[] sectionFormatID) {
176          return (PropertyIDMap) super.get(new String(sectionFormatID));
177      }
178  
179  
180  
181      /**
182       *  <p>
183       *
184       *  Returns the {@link PropertyIDMap} for a given section format ID.</p>
185       *
186       *@param  sectionFormatID  A section format ID as a <tt>byte[]</tt> .
187       *@return                  Description of the Return Value
188       *@deprecated              Use {@link #get(byte[])} instead!
189       */
190      public Object get(final Object sectionFormatID) {
191          return get((byte[]) sectionFormatID);
192      }
193  
194  
195  
196      /**
197       *  <p>
198       *
199       *  Associates a section format ID with a {@link PropertyIDMap}.</p>
200       *
201       *@param  sectionFormatID  Description of the Parameter
202       *@param  propertyIDMap    Description of the Parameter
203       *@return                  Description of the Return Value
204       */
205      public Object put(final byte[] sectionFormatID,
206              final PropertyIDMap propertyIDMap) {
207          return super.put(new String(sectionFormatID), propertyIDMap);
208      }
209  
210  
211  
212      /**
213       *@param  key    Description of the Parameter
214       *@param  value  Description of the Parameter
215       *@return        Description of the Return Value
216       *@deprecated    Use {@link #put(byte[], PropertyIDMap)} instead!
217       */
218      public Object put(final Object key, final Object value) {
219          return put((byte[]) key, (PropertyIDMap) value);
220      }
221  
222  }
223