001: /*
002: * $RCSfile: MediaContainer.java,v $
003: *
004: * Copyright 1997-2008 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
006: *
007: * This code is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU General Public License version 2 only, as
009: * published by the Free Software Foundation. Sun designates this
010: * particular file as subject to the "Classpath" exception as provided
011: * by Sun in the LICENSE file that accompanied this code.
012: *
013: * This code is distributed in the hope that it will be useful, but WITHOUT
014: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
015: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
016: * version 2 for more details (a copy is included in the LICENSE file that
017: * accompanied this code).
018: *
019: * You should have received a copy of the GNU General Public License version
020: * 2 along with this work; if not, write to the Free Software Foundation,
021: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
022: *
023: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
024: * CA 95054 USA or visit www.sun.com if you need additional information or
025: * have any questions.
026: *
027: * $Revision: 1.6 $
028: * $Date: 2008/02/28 20:17:26 $
029: * $State: Exp $
030: */
031:
032: package javax.media.j3d;
033:
034: import java.net.URL;
035: import java.io.InputStream;
036:
037: /**
038: * The MediaContainer object defines all sound data: cached state flag, and
039: * associated sound media. Currently this references the sound media in
040: * one of three forms: URL String, URL object, or InputStream object.
041: * In future releases media data will include references to Java Media
042: * Player objects.
043: * Only one type of sound media data specified using
044: * <code>setURLString</code>, <code>setURLObject</code>,
045: * or <code>setInputStream</code> may be
046: * non-null (or they may all be null). An attempt to set more
047: * than one of these attributes to a non-null reference will
048: * result in an exception being thrown. If all sound media data
049: * references are null, there is no sound associated with this
050: * MediaContainer and Sound nodes referencing this object cannot
051: * be played.
052: */
053: public class MediaContainer extends NodeComponent {
054: /**
055: * For MediaContainer component objects, specifies that this object
056: * allows the reading of its cached flag.
057: */
058: public static final int ALLOW_CACHE_READ = CapabilityBits.MEDIA_CONTAINER_ALLOW_CACHE_READ;
059:
060: /**
061: * For MediaContainer component objects, specifies that this object
062: * allows the writing of its cached flag.
063: */
064: public static final int ALLOW_CACHE_WRITE = CapabilityBits.MEDIA_CONTAINER_ALLOW_CACHE_WRITE;
065:
066: /**
067: * For MediaContainer component objects, specifies that this object
068: * allows the reading of it's sound data.
069: */
070: public static final int ALLOW_URL_READ = CapabilityBits.MEDIA_CONTAINER_ALLOW_URL_READ;
071:
072: /**
073: * For MediaContainer component objects, specifies that this object
074: * allows the writing of it's URL path.
075: */
076: public static final int ALLOW_URL_WRITE = CapabilityBits.MEDIA_CONTAINER_ALLOW_URL_WRITE;
077:
078: // Array for setting default read capabilities
079: private static final int[] readCapabilities = { ALLOW_CACHE_READ,
080: ALLOW_URL_READ };
081:
082: /**
083: * Constructs a MediaContainer object with default parameters.
084: * The default values are as follows:
085: * <ul>
086: * URL String data : null<br>
087: * URL object data : null<br>
088: * InputStream data : null<br>
089: * cache enable : true<br>
090: * </ul>
091: */
092: public MediaContainer() {
093: // Just use default values
094: // set default read capabilities
095: setDefaultReadCapabilities(readCapabilities);
096: }
097:
098: /**
099: * Constructs and initializes a MediaContainer object using specified
100: * parameters.
101: * @param path string of URL path containing sound data
102: * @exception SoundException if the URL is not valid or cannot be opened
103: */
104: public MediaContainer(String path) {
105: // set default read capabilities
106: setDefaultReadCapabilities(readCapabilities);
107:
108: ((MediaContainerRetained) this .retained).setURLString(path);
109: }
110:
111: /**
112: * Constructs and initializes a MediaContainer object using specified
113: * parameters.
114: * @param url URL path containing sound data
115: * @exception SoundException if the URL is not valid or cannot be opened
116: */
117: public MediaContainer(URL url) {
118: // set default read capabilities
119: setDefaultReadCapabilities(readCapabilities);
120:
121: ((MediaContainerRetained) this .retained).setURLObject(url);
122: }
123:
124: /**
125: * Constructs and initializes a MediaContainer object using specified
126: * parameters.
127: * @param stream input stream containing sound data
128: *
129: * @since Java 3D 1.2
130: */
131: public MediaContainer(InputStream stream) {
132: // set default read capabilities
133: setDefaultReadCapabilities(readCapabilities);
134:
135: ((MediaContainerRetained) this .retained).setInputStream(stream);
136: }
137:
138: /**
139: * Creates the retained mode MediaContainerRetained object that this
140: * component object will point to.
141: */
142: void createRetained() {
143: this .retained = new MediaContainerRetained();
144: this .retained.setSource(this );
145: }
146:
147: /**
148: * Set Cache Enable state flag.
149: * Allows the writing of sound data explicitly into the MediaContainer
150: * rather than just referencing a JavaMedia container.
151: * @param flag boolean denoting if sound data is cached in this instance
152: * @exception CapabilityNotSetException if appropriate capability is
153: * not set and this object is part of live or compiled scene graph
154: */
155: public void setCacheEnable(boolean flag) {
156: if (isLiveOrCompiled())
157: if (!this .getCapability(ALLOW_CACHE_WRITE))
158: throw new CapabilityNotSetException(J3dI18N
159: .getString("MediaContainer1"));
160:
161: ((MediaContainerRetained) this .retained).setCacheEnable(flag);
162: }
163:
164: /**
165: * Retrieve Cache Enable state flag.
166: * @return flag denoting is sound data is non-cached or cached
167: * @exception CapabilityNotSetException if appropriate capability is
168: * not set and this object is part of live or compiled scene graph
169: */
170: public boolean getCacheEnable() {
171: if (isLiveOrCompiled())
172: if (!this .getCapability(ALLOW_CACHE_READ))
173: throw new CapabilityNotSetException(J3dI18N
174: .getString("MediaContainer2"));
175:
176: return ((MediaContainerRetained) this .retained)
177: .getCacheEnable();
178: }
179:
180: /**
181: * @deprecated As of Java 3D version 1.2, replaced by
182: * <code>setURLString</code>
183: */
184: public void setURL(String path) {
185: if (isLiveOrCompiled()) {
186: if (!this .getCapability(ALLOW_URL_WRITE))
187: throw new CapabilityNotSetException(J3dI18N
188: .getString("MediaContainer3"));
189: }
190:
191: ((MediaContainerRetained) this .retained).setURLString(path);
192: }
193:
194: /**
195: * @deprecated As of Java 3D version 1.2, replaced by
196: * <code>setURLObject</code>
197: */
198: public void setURL(URL url) {
199: if (isLiveOrCompiled())
200: if (!this .getCapability(ALLOW_URL_WRITE))
201: throw new CapabilityNotSetException(J3dI18N
202: .getString("MediaContainer3"));
203: ((MediaContainerRetained) this .retained).setURLObject(url);
204: }
205:
206: /**
207: * Set URL String.
208: * @param path string of URL containing sound data
209: * @exception CapabilityNotSetException if appropriate capability is
210: * not set and this object is part of live or compiled scene graph
211: * @exception SoundException if the URL is not valid or cannot be opened
212: * @exception IllegalArgumentException if the specified sound data is
213: * non-null and any other sound data reference is also non-null.
214: * @since Java 3D 1.2
215: */
216: public void setURLString(String path) {
217: if (isLiveOrCompiled()) {
218: if (!this .getCapability(ALLOW_URL_WRITE))
219: throw new CapabilityNotSetException(J3dI18N
220: .getString("MediaContainer3"));
221: }
222: ((MediaContainerRetained) this .retained).setURLString(path);
223: }
224:
225: /**
226: * Set URL Object.
227: * @param url URL object containing sound data
228: * @exception CapabilityNotSetException if appropriate capability is
229: * not set and this object is part of live or compiled scene graph
230: * @exception SoundException if the URL is not valid or cannot be opened
231: * @exception IllegalArgumentException if the specified sound data is
232: * non-null and any other sound data reference is also non-null.
233: * @since Java 3D 1.2
234: */
235: public void setURLObject(URL url) {
236: if (isLiveOrCompiled())
237: if (!this .getCapability(ALLOW_URL_WRITE))
238: throw new CapabilityNotSetException(J3dI18N
239: .getString("MediaContainer3"));
240: ((MediaContainerRetained) this .retained).setURLObject(url);
241: }
242:
243: /**
244: * Set Input Stream.
245: * @param stream input stream object containing sound data
246: * @exception CapabilityNotSetException if appropriate capability is
247: * not set and this object is part of live or compiled scene graph
248: * @exception SoundException if InputStream is bad
249: * @exception IllegalArgumentException if the specified sound data is
250: * non-null and any other sound data reference is also non-null.
251: * @since Java 3D 1.2
252: */
253: public void setInputStream(InputStream stream) {
254: if (isLiveOrCompiled())
255: if (!this .getCapability(ALLOW_URL_WRITE))
256: throw new CapabilityNotSetException(J3dI18N
257: .getString("MediaContainer3"));
258: ((MediaContainerRetained) this .retained).setInputStream(stream);
259: }
260:
261: /**
262: * @deprecated As of Java 3D version 1.2, replaced by
263: * <code>getURLString</code>
264: */
265: public String getURL() {
266: if (isLiveOrCompiled())
267: if (!this .getCapability(ALLOW_URL_READ))
268: throw new CapabilityNotSetException(J3dI18N
269: .getString("MediaContainer4"));
270: return ((MediaContainerRetained) this .retained).getURLString();
271: }
272:
273: /**
274: * Retrieve URL String.
275: * @return string of URL containing sound data
276: * @exception CapabilityNotSetException if appropriate capability is
277: * not set and this object is part of live or compiled scene graph
278: * @since Java 3D 1.2
279: */
280: public String getURLString() {
281: if (isLiveOrCompiled())
282: if (!this .getCapability(ALLOW_URL_READ))
283: throw new CapabilityNotSetException(J3dI18N
284: .getString("MediaContainer4"));
285: return ((MediaContainerRetained) this .retained).getURLString();
286: }
287:
288: /**
289: * Retrieve URL Object.
290: * @return URL containing sound data
291: * @exception CapabilityNotSetException if appropriate capability is
292: * not set and this object is part of live or compiled scene graph
293: * @since Java 3D 1.2
294: */
295: public URL getURLObject() {
296: if (isLiveOrCompiled())
297: if (!this .getCapability(ALLOW_URL_READ))
298: throw new CapabilityNotSetException(J3dI18N
299: .getString("MediaContainer4"));
300: return ((MediaContainerRetained) this .retained).getURLObject();
301: }
302:
303: /**
304: * Retrieve Input Stream.
305: * @return reference to input stream containing sound data
306: * @exception CapabilityNotSetException if appropriate capability is
307: * not set and this object is part of live or compiled scene graph
308: * @since Java 3D 1.2
309: */
310: public InputStream getInputStream() {
311: if (isLiveOrCompiled())
312: if (!this .getCapability(ALLOW_URL_READ))
313: throw new CapabilityNotSetException(J3dI18N
314: .getString("MediaContainer4"));
315: return ((MediaContainerRetained) this .retained)
316: .getInputStream();
317: }
318:
319: /**
320: * @deprecated As of Java 3D version 1.2, replaced with
321: * <code>cloneNodeComponent(boolean forceDuplicate)</code>
322: */
323: public NodeComponent cloneNodeComponent() {
324: MediaContainer mc = new MediaContainer();
325: mc.duplicateNodeComponent(this );
326: return mc;
327: }
328:
329: /**
330: * Copies all MediaContainer information from
331: * <code>originalNodeComponent</code> into
332: * the current node. This method is called from the
333: * <code>cloneNodeComponent</code> method and <code>duplicateNodeComponent</code>
334: * method which is, in turn, called by the
335: * <code>cloneTree</code> method.<P>
336: *
337: * @param originalNodeComponent the original node component to duplicate.
338: * @param forceDuplicate when set to <code>true</code>, causes the
339: * <code>duplicateOnCloneTree</code> flag to be ignored. When
340: * <code>false</code>, the value of each node component's
341: * <code>duplicateOnCloneTree</code> variable determines whether
342: * NodeComponent data is duplicated or copied.
343: *
344: * @exception RestrictedAccessException if this object is part of a live
345: * or compiled scenegraph.
346: *
347: * @see Node#cloneTree
348: * @see NodeComponent#setDuplicateOnCloneTree
349: */
350: void duplicateAttributes(NodeComponent originalNodeComponent,
351: boolean forceDuplicate) {
352:
353: super
354: .duplicateAttributes(originalNodeComponent,
355: forceDuplicate);
356:
357: MediaContainerRetained mc = (MediaContainerRetained) originalNodeComponent.retained;
358: MediaContainerRetained rt = (MediaContainerRetained) retained;
359: rt.setCacheEnable(mc.getCacheEnable());
360: rt.setURLString(mc.getURLString(), false);
361: rt.setURLObject(mc.getURLObject(), false);
362: rt.setInputStream(mc.getInputStream(), false);
363: }
364: }
|