2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
4 * Copyright 2013-2014 Oracle and/or its affiliates. All rights reserved.
6 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.
7 * Other names may be trademarks of their respective owners.
9 * The contents of this file are subject to the terms of either the GNU
10 * General Public License Version 2 only ("GPL") or the Common
11 * Development and Distribution License("CDDL") (collectively, the
12 * "License"). You may not use this file except in compliance with the
13 * License. You can obtain a copy of the License at
14 * http://www.netbeans.org/cddl-gplv2.html
15 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
16 * specific language governing permissions and limitations under the
17 * License. When distributing the software, include this License Header
18 * Notice in each file and include the License file at
19 * nbbuild/licenses/CDDL-GPL-2-CP. Oracle designates this
20 * particular file as subject to the "Classpath" exception as provided
21 * by Oracle in the GPL Version 2 section of the License file that
22 * accompanied this code. If applicable, add the following below the
23 * License Header, with the fields enclosed by brackets [] replaced by
24 * your own identifying information:
25 * "Portions Copyrighted [year] [name of copyright owner]"
29 * The Original Software is NetBeans. The Initial Developer of the Original
30 * Software is Oracle. Portions Copyright 2013-2014 Oracle. All Rights Reserved.
32 * If you wish your version of this file to be governed by only the CDDL
33 * or only the GPL Version 2, indicate your decision by adding
34 * "[Contributor] elects to include this software in this distribution
35 * under the [CDDL or GPL Version 2] license." If you do not indicate a
36 * single choice of license, a recipient has the option to distribute
37 * your version of this file under either the CDDL, the GPL Version 2 or
38 * to extend the choice of license to its licensees as provided above.
39 * However, if you add GPL Version 2 code and therefore, elected the GPL
40 * Version 2 license, then the option applies only if the new code is
41 * made subject to such option by the copyright holder.
43 package net.java.html.sound;
45 import java.util.ServiceLoader;
46 import org.apidesign.html.sound.spi.AudioEnvironment;
48 /** Handle to an audio clip which can be {@link #play() played}, {@link #pause() paused}
49 * and etc. Obtain new instance via {@link #create(java.lang.String) create} factory
50 * method and then use it when necessary.
54 public abstract class AudioClip {
58 /** Creates new instance of an audio clip based on the provided URL.
59 * If no suitable audio environment provider is found, the method
60 * returns a dummy instance that does nothing and only returns
61 * false from its {@link #isSupported()} method.
63 * @param src the URL where to find the audio clip
64 * @return the audio clip handle
65 * @throws NullPointerException if src is <code>null</code>
67 public static AudioClip create(String src) {
69 for (AudioEnvironment<?> ae : ServiceLoader.load(AudioEnvironment.class)) {
70 Impl handle = create(ae, src);
75 return DummyClip.INSTANCE;
78 /** Plays the clip from begining to the end.
80 public abstract void play();
82 /** Pauses playback of the clip
84 public abstract void pause();
87 * Specifies the volume of the audio. Must be a number between 0.0 and 1.0:
89 * <li>1.0 - highest volume</li>
90 * <li>0.5 - 50% volume</li>
91 * <li>0.0 - silent</li>
94 * @param volume for the playback
96 public abstract void setVolume(double volume);
98 /** Check whether the audio clip is supported and can be played.
99 * @return true if it is likely that after calling {@link #play()}
100 * a sound will be produced
102 public abstract boolean isSupported();
104 // public abstract void playFrom(int seconds);
110 private static <Audio> Impl<Audio> create(AudioEnvironment<Audio> env, String src) {
111 Audio a = env.create(src);
113 return new Impl<Audio>(env, src, a);
119 private static final class Impl<Audio> extends AudioClip {
120 private final String src;
121 private final Audio clip;
122 private final AudioEnvironment<Audio> env;
124 public Impl(AudioEnvironment<Audio> env, String src, Audio clip) {
136 public void pause() {
141 public void setVolume(double volume) {
142 env.setVolume(clip, volume);
146 public boolean isSupported() {
147 return env.isSupported(clip);
151 public int hashCode() {
152 return 59 * src.hashCode();
156 public boolean equals(Object obj) {
157 if (obj instanceof Impl) {
158 return src.equals(((Impl)obj).src);
164 private static final class DummyClip extends AudioClip {
165 static AudioClip INSTANCE = new DummyClip();
172 public void pause() {
176 public void setVolume(double volume) {
180 public boolean isSupported() {
183 } // end of DummyClip