# HG changeset patch # User ddehaven # Date 1408469536 25200 # Node ID 508779ce66199dd6084e167ddab8362ad7578fb6 # Parent e9b05e933dddced8537db47929915b2cd05886f4# Parent 541d3bb1825e6145951d054ab7793251b245f32c Merge diff -r e9b05e933ddd -r 508779ce6619 jdk/make/CopyIntoClasses.gmk --- a/jdk/make/CopyIntoClasses.gmk Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/make/CopyIntoClasses.gmk Tue Aug 19 10:32:16 2014 -0700 @@ -164,15 +164,15 @@ ################################################################################ ifneq ($(OPENJDK_TARGET_OS), macosx) - OPENJDK_TARGET_OS_FLAVORMAP_PROPERTIES = $(JDK_TOPDIR)/src/$(OPENJDK_TARGET_OS_API_DIR)/classes/sun/awt/datatransfer/flavormap.properties + OPENJDK_TARGET_OS_FLAVORMAP_PROPERTIES = $(JDK_TOPDIR)/src/java.desktop/$(OPENJDK_TARGET_OS_API_DIR)/classes/sun/datatransfer/resources/flavormap.properties else - OPENJDK_TARGET_OS_FLAVORMAP_PROPERTIES = $(JDK_TOPDIR)/src/macosx/classes/sun/awt/datatransfer/flavormap.properties + OPENJDK_TARGET_OS_FLAVORMAP_PROPERTIES = $(JDK_TOPDIR)/src/java.desktop/macosx/classes/sun/datatransfer/resources/flavormap.properties endif -$(JDK_OUTPUTDIR)/classes/sun/awt/datatransfer/flavormap.properties: $(OPENJDK_TARGET_OS_FLAVORMAP_PROPERTIES) +$(JDK_OUTPUTDIR)/classes/sun/datatransfer/resources/flavormap.properties: $(OPENJDK_TARGET_OS_FLAVORMAP_PROPERTIES) $(install-file) -COPY_EXTRA += $(JDK_OUTPUTDIR)/classes/sun/awt/datatransfer/flavormap.properties +COPY_EXTRA += $(JDK_OUTPUTDIR)/classes/sun/datatransfer/resources/flavormap.properties ################################################################################ diff -r e9b05e933ddd -r 508779ce6619 jdk/src/demo/share/jfc/Font2DTest/resources/TextResources.properties --- a/jdk/src/demo/share/jfc/Font2DTest/resources/TextResources.properties Mon Aug 18 14:03:21 2014 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,1 +0,0 @@ -string=This is Java 2D! (Default) diff -r e9b05e933ddd -r 508779ce6619 jdk/src/demo/share/jfc/Font2DTest/resources/TextResources_de.properties --- a/jdk/src/demo/share/jfc/Font2DTest/resources/TextResources_de.properties Mon Aug 18 14:03:21 2014 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,1 +0,0 @@ -string=This is Java 2D! (German) \u00f6 \u00df \u00dc diff -r e9b05e933ddd -r 508779ce6619 jdk/src/demo/share/jfc/Font2DTest/resources/TextResources_en.properties --- a/jdk/src/demo/share/jfc/Font2DTest/resources/TextResources_en.properties Mon Aug 18 14:03:21 2014 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,1 +0,0 @@ -string=This is Java 2D! (English) A B C diff -r e9b05e933ddd -r 508779ce6619 jdk/src/demo/share/jfc/Font2DTest/resources/TextResources_en_GB.properties --- a/jdk/src/demo/share/jfc/Font2DTest/resources/TextResources_en_GB.properties Mon Aug 18 14:03:21 2014 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,1 +0,0 @@ -string=This is Java 2D! (English in Great Britain) \u0075 \u006b Z diff -r e9b05e933ddd -r 508779ce6619 jdk/src/demo/share/jfc/Font2DTest/resources/TextResources_ja.properties --- a/jdk/src/demo/share/jfc/Font2DTest/resources/TextResources_ja.properties Mon Aug 18 14:03:21 2014 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,1 +0,0 @@ -string=Java 2D\u3067\u3059\u3002(\u30C7\u30D5\u30A9\u30EB\u30C8) diff -r e9b05e933ddd -r 508779ce6619 jdk/src/demo/share/jfc/Font2DTest/resources/TextResources_ko.properties --- a/jdk/src/demo/share/jfc/Font2DTest/resources/TextResources_ko.properties Mon Aug 18 14:03:21 2014 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,1 +0,0 @@ -string=This is Java 2D! (Korean) diff -r e9b05e933ddd -r 508779ce6619 jdk/src/demo/share/jfc/Font2DTest/resources/TextResources_zh_CN.properties --- a/jdk/src/demo/share/jfc/Font2DTest/resources/TextResources_zh_CN.properties Mon Aug 18 14:03:21 2014 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,1 +0,0 @@ -string=\u8FD9\u662F Java 2D! (\u9ED8\u8BA4\u503C) diff -r e9b05e933ddd -r 508779ce6619 jdk/src/demo/share/jfc/Font2DTest/resources/resource.data --- a/jdk/src/demo/share/jfc/Font2DTest/resources/resource.data Mon Aug 18 14:03:21 2014 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -en US -en GB -ko KO -ab KO -de DE diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/macosx/classes/apple/laf/JRSUIControl.java --- a/jdk/src/java.desktop/macosx/classes/apple/laf/JRSUIControl.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/macosx/classes/apple/laf/JRSUIControl.java Tue Aug 19 10:32:16 2014 -0700 @@ -114,7 +114,7 @@ changes.putAll(other.changes); } - protected synchronized final void finalize() throws Throwable { + protected synchronized void finalize() throws Throwable { if (cfDictionaryPtr == 0) return; disposeCFDictionary(cfDictionaryPtr); cfDictionaryPtr = 0; diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/macosx/classes/com/apple/laf/AquaInternalFrameUI.java --- a/jdk/src/java.desktop/macosx/classes/com/apple/laf/AquaInternalFrameUI.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/macosx/classes/com/apple/laf/AquaInternalFrameUI.java Tue Aug 19 10:32:16 2014 -0700 @@ -938,7 +938,11 @@ final Point pt = new Point(); final Component c = getComponentToForwardTo(e, pt); if (c == null) return; - c.dispatchEvent(new MouseWheelEvent(c, e.getID(), e.getWhen(), e.getModifiers(), pt.x, pt.y, e.getClickCount(), e.isPopupTrigger(), e.getScrollType(), e.getScrollAmount(), e.getWheelRotation())); + c.dispatchEvent(new MouseWheelEvent(c, e.getID(), e.getWhen(), + e.getModifiers(), pt.x, pt.y, e.getXOnScreen(), e.getYOnScreen(), + e.getClickCount(), e.isPopupTrigger(), e.getScrollType(), + e.getScrollAmount(), e.getWheelRotation(), + e.getPreciseWheelRotation())); } public void componentResized(final ComponentEvent e) { diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/macosx/classes/com/apple/laf/AquaTabbedPaneCopyFromBasicUI.java --- a/jdk/src/java.desktop/macosx/classes/com/apple/laf/AquaTabbedPaneCopyFromBasicUI.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/macosx/classes/com/apple/laf/AquaTabbedPaneCopyFromBasicUI.java Tue Aug 19 10:32:16 2014 -0700 @@ -3307,7 +3307,7 @@ pane.repaint(); } else if (name == "indexForTitle") { calculatedBaseline = false; - updateHtmlViews((Integer) e.getNewValue()); + updateHtmlViews((Integer) e.getNewValue(), false); } else if (name == "tabLayoutPolicy") { AquaTabbedPaneCopyFromBasicUI.this.uninstallUI(pane); AquaTabbedPaneCopyFromBasicUI.this.installUI(pane); @@ -3345,7 +3345,7 @@ calculatedBaseline = false; } else if (name == "indexForNullComponent") { isRunsDirty = true; - updateHtmlViews((Integer) e.getNewValue()); + updateHtmlViews((Integer) e.getNewValue(), true); } else if (name == "font") { calculatedBaseline = false; } @@ -3464,10 +3464,10 @@ return; } isRunsDirty = true; - updateHtmlViews(tp.indexOfComponent(child)); + updateHtmlViews(tp.indexOfComponent(child), true); } - private void updateHtmlViews(int index) { + private void updateHtmlViews(int index, boolean inserted) { final String title = tabPane.getTitleAt(index); final boolean isHTML = BasicHTML.isHTMLString(title); if (isHTML) { @@ -3475,16 +3475,24 @@ htmlViews = createHTMLVector(); } else { // Vector already exists final View v = BasicHTML.createHTMLView(tabPane, title); - htmlViews.insertElementAt(v, index); + setHtmlView(v, inserted, index); } } else { // Not HTML if (htmlViews != null) { // Add placeholder - htmlViews.insertElementAt(null, index); + setHtmlView(null, inserted, index); } // else nada! } updateMnemonics(); } + private void setHtmlView(View v, boolean inserted, int index) { + if (inserted || index >= htmlViews.size()) { + htmlViews.insertElementAt(v, index); + } else { + htmlViews.setElementAt(v, index); + } + } + public void componentRemoved(final ContainerEvent e) { final JTabbedPane tp = (JTabbedPane)e.getContainer(); final Component child = e.getChild(); diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/macosx/classes/sun/font/CFontManager.java --- a/jdk/src/java.desktop/macosx/classes/sun/font/CFontManager.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/macosx/classes/sun/font/CFontManager.java Tue Aug 19 10:32:16 2014 -0700 @@ -43,7 +43,7 @@ import sun.awt.util.ThreadGroupUtils; import sun.lwawt.macosx.*; -public class CFontManager extends SunFontManager { +public final class CFontManager extends SunFontManager { private FontConfigManager fcManager = null; private static Hashtable genericFonts = new Hashtable(); @@ -61,20 +61,14 @@ return new CFontConfiguration(this, preferLocaleFonts, preferPropFonts); } - private static String[] defaultPlatformFont = null; - /* * Returns an array of two strings. The first element is the * name of the font. The second element is the file name. */ @Override - public synchronized String[] getDefaultPlatformFont() { - if (defaultPlatformFont == null) { - defaultPlatformFont = new String[2]; - defaultPlatformFont[0] = "Lucida Grande"; - defaultPlatformFont[1] = "/System/Library/Fonts/LucidaGrande.ttc"; - } - return defaultPlatformFont; + protected String[] getDefaultPlatformFont() { + return new String[]{"Lucida Grande", + "/System/Library/Fonts/LucidaGrande.ttc"}; } // This is a way to register any kind of Font2D, not just files and composites. diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/macosx/classes/sun/lwawt/LWComponentPeer.java --- a/jdk/src/java.desktop/macosx/classes/sun/lwawt/LWComponentPeer.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/macosx/classes/sun/lwawt/LWComponentPeer.java Tue Aug 19 10:32:16 2014 -0700 @@ -1233,11 +1233,13 @@ delegate, me.getID(), me.getWhen(), me.getModifiers(), me.getX(), me.getY(), + me.getXOnScreen(), me.getYOnScreen(), me.getClickCount(), me.isPopupTrigger(), me.getScrollType(), me.getScrollAmount(), - me.getWheelRotation()); + me.getWheelRotation(), + me.getPreciseWheelRotation()); } else if (e instanceof MouseEvent) { MouseEvent me = (MouseEvent) e; diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/macosx/classes/sun/lwawt/LWWindowPeer.java --- a/jdk/src/java.desktop/macosx/classes/sun/lwawt/LWWindowPeer.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/macosx/classes/sun/lwawt/LWWindowPeer.java Tue Aug 19 10:32:16 2014 -0700 @@ -105,6 +105,8 @@ private final SecurityWarningWindow warningWindow; + private volatile boolean targetFocusable; + /** * Current modal blocker or null. * @@ -240,13 +242,12 @@ if (!visible && warningWindow != null) { warningWindow.setVisible(false, false); } - + updateFocusableWindowState(); super.setVisibleImpl(visible); // TODO: update graphicsConfig, see 4868278 platformWindow.setVisible(visible); if (isSimpleWindow()) { KeyboardFocusManagerPeer kfmPeer = LWKeyboardFocusManagerPeer.getInstance(); - if (visible) { if (!getTarget().isAutoRequestFocus()) { return; @@ -397,6 +398,7 @@ @Override public void updateFocusableWindowState() { + targetFocusable = getTarget().isFocusableWindow(); platformWindow.updateFocusableWindowState(); } @@ -1220,13 +1222,13 @@ } private boolean isFocusableWindow() { - boolean focusable = getTarget().isFocusableWindow(); + boolean focusable = targetFocusable; if (isSimpleWindow()) { LWWindowPeer ownerPeer = getOwnerFrameDialog(this); if (ownerPeer == null) { return false; } - return focusable && ownerPeer.getTarget().isFocusableWindow(); + return focusable && ownerPeer.targetFocusable; } return focusable; } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/macosx/classes/sun/lwawt/macosx/CEmbeddedFrame.java --- a/jdk/src/java.desktop/macosx/classes/sun/lwawt/macosx/CEmbeddedFrame.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/macosx/classes/sun/lwawt/macosx/CEmbeddedFrame.java Tue Aug 19 10:32:16 2014 -0700 @@ -38,7 +38,8 @@ private CPlatformResponder responder; private static final Object classLock = new Object(); - private static volatile CEmbeddedFrame focusedWindow; + private static volatile CEmbeddedFrame globalFocusedWindow; + private CEmbeddedFrame browserWindowFocusedApplet; private boolean parentWindowActive = true; public CEmbeddedFrame() { @@ -111,10 +112,10 @@ synchronized (classLock) { // In some cases an applet may not receive the focus lost event // from the parent window (see 8012330) - focusedWindow = (focused) ? this - : ((focusedWindow == this) ? null : focusedWindow); + globalFocusedWindow = (focused) ? this + : ((globalFocusedWindow == this) ? null : globalFocusedWindow); } - if (focusedWindow == this) { + if (globalFocusedWindow == this) { // see bug 8010925 // we can't put this to handleWindowFocusEvent because // it won't be invoced if focuse is moved to a html element @@ -145,9 +146,23 @@ // non-focused applet. This method can be called from different threads. public void handleWindowFocusEvent(boolean parentWindowActive) { this.parentWindowActive = parentWindowActive; + // If several applets are running in different browser's windows, it is necessary to + // detect the switching between the parent windows and update globalFocusedWindow accordingly. + synchronized (classLock) { + if (!parentWindowActive) { + this.browserWindowFocusedApplet = globalFocusedWindow; + } + if (parentWindowActive && globalFocusedWindow != this && isParentWindowChanged()) { + // It looks like we have switched to another browser window, let's restore focus to + // the previously focused applet in this window. If no applets were focused in the + // window, we will set focus to the first applet in the window. + globalFocusedWindow = (this.browserWindowFocusedApplet != null) ? this.browserWindowFocusedApplet + : this; + } + } // ignore focus "lost" native request as it may mistakenly // deactivate active window (see 8001161) - if (focusedWindow == this && parentWindowActive) { + if (globalFocusedWindow == this && parentWindowActive) { responder.handleWindowFocusEvent(parentWindowActive, null); } } @@ -155,4 +170,10 @@ public boolean isParentWindowActive() { return parentWindowActive; } + + private boolean isParentWindowChanged() { + // If globalFocusedWindow is located at inactive parent window or null, we have swithed to + // another window. + return globalFocusedWindow != null ? !globalFocusedWindow.isParentWindowActive() : true; + } } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/macosx/classes/sun/lwawt/macosx/NSPrintInfo.java --- a/jdk/src/java.desktop/macosx/classes/sun/lwawt/macosx/NSPrintInfo.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/macosx/classes/sun/lwawt/macosx/NSPrintInfo.java Tue Aug 19 10:32:16 2014 -0700 @@ -54,11 +54,11 @@ return "" + fNSPrintInfo; } - public final Class getCategory() { + public Class getCategory() { return NSPrintInfo.class; } - public final String getName() { + public String getName() { return "nsPrintInfo"; } } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/macosx/native/libawt_lwawt/sun/awt/JavaComponentAccessibility.m --- a/jdk/src/java.desktop/macosx/native/libawt_lwawt/sun/awt/JavaComponentAccessibility.m Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/macosx/native/libawt_lwawt/sun/awt/JavaComponentAccessibility.m Tue Aug 19 10:32:16 2014 -0700 @@ -1108,7 +1108,10 @@ JNIEnv *env = [ThreadUtilities getJNIEnv]; id value = nil; + NSWindow* hostWindow = [[self->fView window] retain]; jobject focused = JNFCallStaticObjectMethod(env, jm_getFocusOwner, fComponent); // AWT_THREADING Safe (AWTRunLoop) + [hostWindow release]; + if (focused != NULL) { if (JNFIsInstanceOf(env, focused, &sjc_Accessible)) { value = [JavaComponentAccessibility createWithAccessible:focused withEnv:env withView:fView]; diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/com/sun/media/sound/FFT.java --- a/jdk/src/java.desktop/share/classes/com/sun/media/sound/FFT.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/com/sun/media/sound/FFT.java Tue Aug 19 10:32:16 2014 -0700 @@ -68,7 +68,7 @@ calc(fftFrameSize, data, sign, w); } - private final static double[] computeTwiddleFactors(int fftFrameSize, + private static double[] computeTwiddleFactors(int fftFrameSize, int sign) { int imax = (int) (Math.log(fftFrameSize) / Math.log(2.)); @@ -122,7 +122,7 @@ return warray; } - private final static void calc(int fftFrameSize, double[] data, int sign, + private static void calc(int fftFrameSize, double[] data, int sign, double[] w) { final int fftFrameSize2 = fftFrameSize << 1; @@ -139,7 +139,7 @@ } - private final static void calcF2E(int fftFrameSize, double[] data, int i, + private static void calcF2E(int fftFrameSize, double[] data, int i, int nstep, double[] w) { int jmax = nstep; for (int n = 0; n < jmax; n += 2) { @@ -163,7 +163,7 @@ // Perform Factor-4 Decomposition with 3 * complex operators and 8 +/- // complex operators - private final static void calcF4F(int fftFrameSize, double[] data, int i, + private static void calcF4F(int fftFrameSize, double[] data, int i, int nstep, double[] w) { final int fftFrameSize2 = fftFrameSize << 1; // 2*fftFrameSize; // Factor-4 Decomposition @@ -331,7 +331,7 @@ // Perform Factor-4 Decomposition with 3 * complex operators and 8 +/- // complex operators - private final static void calcF4I(int fftFrameSize, double[] data, int i, + private static void calcF4I(int fftFrameSize, double[] data, int i, int nstep, double[] w) { final int fftFrameSize2 = fftFrameSize << 1; // 2*fftFrameSize; // Factor-4 Decomposition @@ -499,7 +499,7 @@ // Perform Factor-4 Decomposition with 3 * complex operators and 8 +/- // complex operators - private final static void calcF4FE(int fftFrameSize, double[] data, int i, + private static void calcF4FE(int fftFrameSize, double[] data, int i, int nstep, double[] w) { final int fftFrameSize2 = fftFrameSize << 1; // 2*fftFrameSize; // Factor-4 Decomposition @@ -593,7 +593,7 @@ // Perform Factor-4 Decomposition with 3 * complex operators and 8 +/- // complex operators - private final static void calcF4IE(int fftFrameSize, double[] data, int i, + private static void calcF4IE(int fftFrameSize, double[] data, int i, int nstep, double[] w) { final int fftFrameSize2 = fftFrameSize << 1; // 2*fftFrameSize; // Factor-4 Decomposition @@ -685,7 +685,7 @@ } - private final void bitreversal(double[] data) { + private void bitreversal(double[] data) { if (fftFrameSize < 4) return; diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/com/sun/media/sound/JDK13Services.java --- a/jdk/src/java.desktop/share/classes/com/sun/media/sound/JDK13Services.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/com/sun/media/sound/JDK13Services.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -25,6 +25,8 @@ package com.sun.media.sound; +import java.security.AccessController; +import java.security.PrivilegedAction; import java.util.ArrayList; import java.util.Collections; import java.util.List; @@ -176,11 +178,11 @@ && !Sequencer.class.equals(typeClass)) { return null; } - String value; - String propertyName = typeClass.getName(); - value = JSSecurityManager.getProperty(propertyName); + String name = typeClass.getName(); + String value = AccessController.doPrivileged( + (PrivilegedAction) () -> System.getProperty(name)); if (value == null) { - value = getProperties().getProperty(propertyName); + value = getProperties().getProperty(name); } if ("".equals(value)) { value = null; diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/com/sun/media/sound/JSSecurityManager.java --- a/jdk/src/java.desktop/share/classes/com/sun/media/sound/JSSecurityManager.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/com/sun/media/sound/JSSecurityManager.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -73,33 +73,6 @@ } } - static String getProperty(final String propertyName) { - String propertyValue; - if (hasSecurityManager()) { - if(Printer.debug) Printer.debug("using JDK 1.2 security to get property"); - try{ - PrivilegedAction action = new PrivilegedAction() { - public String run() { - try { - return System.getProperty(propertyName); - } catch (Throwable t) { - return null; - } - } - }; - propertyValue = AccessController.doPrivileged(action); - } catch( Exception e ) { - if(Printer.debug) Printer.debug("not using JDK 1.2 security to get properties"); - propertyValue = System.getProperty(propertyName); - } - } else { - if(Printer.debug) Printer.debug("not using JDK 1.2 security to get properties"); - propertyValue = System.getProperty(propertyName); - } - return propertyValue; - } - - /** Load properties from a file. This method tries to load properties from the filename give into the passed properties object. diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/com/sun/media/sound/Platform.java --- a/jdk/src/java.desktop/share/classes/com/sun/media/sound/Platform.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/com/sun/media/sound/Platform.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -74,17 +74,6 @@ // intel is little-endian. sparc is big-endian. private static boolean bigEndian; - // this is the value of the "java.home" system property. i am looking it up here - // for use when trying to load the soundbank, just so - // that all the privileged code is localized in this file.... - private static String javahome; - - // this is the value of the "java.class.path" system property - private static String classpath; - - - - static { if(Printer.trace)Printer.trace(">> Platform.java: static"); @@ -129,26 +118,6 @@ return signed8; } - - /** - * Obtain javahome. - * $$kk: 04.16.99: this is *bad*!! - */ - static String getJavahome() { - - return javahome; - } - - /** - * Obtain classpath. - * $$jb: 04.21.99: this is *bad* too!! - */ - static String getClasspath() { - - return classpath; - } - - // PRIVATE METHODS /** @@ -157,21 +126,13 @@ private static void loadLibraries() { if(Printer.trace)Printer.trace(">>Platform.loadLibraries"); - try { - // load the main library - AccessController.doPrivileged(new PrivilegedAction() { - @Override - public Void run() { - System.loadLibrary(libNameMain); - return null; - } - }); - // just for the heck of it... - loadedLibs |= LIB_MAIN; - } catch (SecurityException e) { - if(Printer.err)Printer.err("Security exception loading main native library. JavaSound requires access to these resources."); - throw(e); - } + // load the main library + AccessController.doPrivileged((PrivilegedAction) () -> { + System.loadLibrary(libNameMain); + return null; + }); + // just for the heck of it... + loadedLibs |= LIB_MAIN; // now try to load extra libs. They are defined at compile time in the Makefile // with the define EXTRA_SOUND_JNI_LIBS @@ -181,12 +142,9 @@ while (st.hasMoreTokens()) { final String lib = st.nextToken(); try { - AccessController.doPrivileged(new PrivilegedAction() { - @Override - public Void run() { - System.loadLibrary(lib); - return null; - } + AccessController.doPrivileged((PrivilegedAction) () -> { + System.loadLibrary(lib); + return null; }); if (lib.equals(libNameALSA)) { @@ -239,7 +197,5 @@ // $$fb 2002-03-06: implement check for endianness in native. Facilitates porting ! bigEndian = nIsBigEndian(); signed8 = nIsSigned8(); // Solaris on Sparc: signed, all others unsigned - javahome = JSSecurityManager.getProperty("java.home"); - classpath = JSSecurityManager.getProperty("java.class.path"); } } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/com/sun/media/sound/RIFFReader.java --- a/jdk/src/java.desktop/share/classes/com/sun/media/sound/RIFFReader.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/com/sun/media/sound/RIFFReader.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2007, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -39,21 +39,20 @@ private long filepointer = 0; private final String fourcc; private String riff_type = null; - private long ckSize = 0; + private long ckSize = Integer.MAX_VALUE; private InputStream stream; - private long avail; + private long avail = Integer.MAX_VALUE; private RIFFReader lastiterator = null; public RIFFReader(InputStream stream) throws IOException { - if (stream instanceof RIFFReader) - root = ((RIFFReader)stream).root; - else + if (stream instanceof RIFFReader) { + root = ((RIFFReader) stream).root; + } else { root = this; + } this.stream = stream; - avail = Integer.MAX_VALUE; - ckSize = Integer.MAX_VALUE; // Check for RIFF null paddings, int b; @@ -76,10 +75,12 @@ readFully(fourcc, 1, 3); this.fourcc = new String(fourcc, "ascii"); ckSize = readUnsignedInt(); - - avail = this.ckSize; + avail = ckSize; if (getFormat().equals("RIFF") || getFormat().equals("LIST")) { + if (avail > Integer.MAX_VALUE) { + throw new RIFFInvalidDataException("Chunk size too big"); + } byte[] format = new byte[4]; readFully(format); this.riff_type = new String(format, "ascii"); @@ -118,19 +119,23 @@ } public int read() throws IOException { - if (avail == 0) + if (avail == 0) { return -1; + } int b = stream.read(); - if (b == -1) + if (b == -1) { + avail = 0; return -1; + } avail--; filepointer++; return b; } public int read(byte[] b, int offset, int len) throws IOException { - if (avail == 0) + if (avail == 0) { return -1; + } if (len > avail) { int rlen = stream.read(b, offset, (int)avail); if (rlen != -1) @@ -139,19 +144,21 @@ return rlen; } else { int ret = stream.read(b, offset, len); - if (ret == -1) + if (ret == -1) { + avail = 0; return -1; + } avail -= ret; filepointer += ret; return ret; } } - public final void readFully(byte b[]) throws IOException { + public void readFully(byte b[]) throws IOException { readFully(b, 0, b.length); } - public final void readFully(byte b[], int off, int len) throws IOException { + public void readFully(byte b[], int off, int len) throws IOException { if (len < 0) throw new IndexOutOfBoundsException(); while (len > 0) { @@ -165,7 +172,7 @@ } } - public final long skipBytes(long n) throws IOException { + public long skipBytes(long n) throws IOException { if (n < 0) return 0; long skipped = 0; @@ -191,8 +198,10 @@ return len; } else { long ret = stream.skip(n); - if (ret == -1) + if (ret == -1) { + avail = 0; return -1; + } avail -= ret; filepointer += ret; return ret; @@ -210,8 +219,13 @@ } // Read ASCII chars from stream - public String readString(int len) throws IOException { - byte[] buff = new byte[len]; + public String readString(final int len) throws IOException { + final byte[] buff; + try { + buff = new byte[len]; + } catch (final OutOfMemoryError oom) { + throw new IOException("Length too big", oom); + } readFully(buff); for (int i = 0; i < buff.length; i++) { if (buff[i] == 0) { diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/com/sun/media/sound/SF2Soundbank.java --- a/jdk/src/java.desktop/share/classes/com/sun/media/sound/SF2Soundbank.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/com/sun/media/sound/SF2Soundbank.java Tue Aug 19 10:32:16 2014 -0700 @@ -276,6 +276,9 @@ count--; } + if (presets_bagNdx.isEmpty()) { + throw new RIFFInvalidDataException(); + } int offset = presets_bagNdx.get(0); // Offset should be 0 (but just case) for (int i = 0; i < offset; i++) { @@ -360,6 +363,9 @@ count--; } + if (instruments_bagNdx.isEmpty()) { + throw new RIFFInvalidDataException(); + } int offset = instruments_bagNdx.get(0); // Offset should be 0 (but just case) for (int i = 0; i < offset; i++) { @@ -401,6 +407,9 @@ modulator.amount = chunk.readShort(); modulator.amountSourceOperator = chunk.readUnsignedShort(); modulator.transportOperator = chunk.readUnsignedShort(); + if (i < 0 || i >= instruments_splits_gen.size()) { + throw new RIFFInvalidDataException(); + } SF2LayerRegion split = instruments_splits_gen.get(i); if (split != null) split.modulators.add(modulator); @@ -424,7 +433,8 @@ sample.name = chunk.readString(20); long start = chunk.readUnsignedInt(); long end = chunk.readUnsignedInt(); - sample.data = sampleData.subbuffer(start * 2, end * 2, true); + if (sampleData != null) + sample.data = sampleData.subbuffer(start * 2, end * 2, true); if (sampleData24 != null) sample.data24 = sampleData24.subbuffer(start, end, true); /* @@ -462,6 +472,9 @@ int sampleid = split.generators.get( SF2LayerRegion.GENERATOR_SAMPLEID); split.generators.remove(SF2LayerRegion.GENERATOR_SAMPLEID); + if (sampleid < 0 || sampleid >= samples.size()) { + throw new RIFFInvalidDataException(); + } split.sample = samples.get(sampleid); } else { globalsplit = split; @@ -488,6 +501,9 @@ int instrumentid = split.generators.get( SF2InstrumentRegion.GENERATOR_INSTRUMENT); split.generators.remove(SF2LayerRegion.GENERATOR_INSTRUMENT); + if (instrumentid < 0 || instrumentid >= layers.size()) { + throw new RIFFInvalidDataException(); + } split.layer = layers.get(instrumentid); } else { globalsplit = split; diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/com/sun/media/sound/SoftMidiAudioFileReader.java --- a/jdk/src/java.desktop/share/classes/com/sun/media/sound/SoftMidiAudioFileReader.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/com/sun/media/sound/SoftMidiAudioFileReader.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2007, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -22,6 +22,7 @@ * or visit www.oracle.com if you need additional information or have any * questions. */ + package com.sun.media.sound; import java.io.File; @@ -39,14 +40,14 @@ import javax.sound.midi.Sequence; import javax.sound.midi.Track; import javax.sound.sampled.AudioFileFormat; +import javax.sound.sampled.AudioFileFormat.Type; import javax.sound.sampled.AudioFormat; import javax.sound.sampled.AudioInputStream; import javax.sound.sampled.UnsupportedAudioFileException; -import javax.sound.sampled.AudioFileFormat.Type; import javax.sound.sampled.spi.AudioFileReader; /** - * MIDI File Audio Renderer/Reader + * MIDI File Audio Renderer/Reader. * * @author Karl Helgason */ @@ -109,6 +110,9 @@ if (divtype == Sequence.PPQ) { if (((MetaMessage) msg).getType() == 0x51) { byte[] data = ((MetaMessage) msg).getData(); + if (data.length < 3) { + throw new UnsupportedAudioFileException(); + } mpq = ((data[0] & 0xff) << 16) | ((data[1] & 0xff) << 8) | (data[2] & 0xff); } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/com/sun/media/sound/SoftSynthesizer.java --- a/jdk/src/java.desktop/share/classes/com/sun/media/sound/SoftSynthesizer.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/com/sun/media/sound/SoftSynthesizer.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2008, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2008, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -28,6 +28,7 @@ import java.io.BufferedInputStream; import java.io.File; import java.io.FileInputStream; +import java.io.FileNotFoundException; import java.io.FileOutputStream; import java.io.IOException; import java.io.InputStream; @@ -732,31 +733,28 @@ * Save generated soundbank to disk for faster future use. */ OutputStream out = AccessController - .doPrivileged(new PrivilegedAction() { - public OutputStream run() { - try { - File userhome = new File(System - .getProperty("user.home"), - ".gervill"); - if (!userhome.exists()) - userhome.mkdirs(); - File emg_soundbank_file = new File( - userhome, "soundbank-emg.sf2"); - if (emg_soundbank_file.exists()) - return null; - return new FileOutputStream( - emg_soundbank_file); - } catch (IOException e) { - } catch (SecurityException e) { + .doPrivileged((PrivilegedAction) () -> { + try { + File userhome = new File(System + .getProperty("user.home"), ".gervill"); + if (!userhome.exists()) { + userhome.mkdirs(); } - return null; + File emg_soundbank_file = new File( + userhome, "soundbank-emg.sf2"); + if (emg_soundbank_file.exists()) { + return null; + } + return new FileOutputStream(emg_soundbank_file); + } catch (final FileNotFoundException ignored) { } + return null; }); if (out != null) { try { ((SF2Soundbank) defaultSoundBank).save(out); out.close(); - } catch (IOException e) { + } catch (final IOException ignored) { } } } @@ -846,26 +844,24 @@ private Properties getStoredProperties() { return AccessController - .doPrivileged(new PrivilegedAction() { - public Properties run() { - Properties p = new Properties(); - String notePath = "/com/sun/media/sound/softsynthesizer"; - try { - Preferences prefroot = Preferences.userRoot(); - if (prefroot.nodeExists(notePath)) { - Preferences prefs = prefroot.node(notePath); - String[] prefs_keys = prefs.keys(); - for (String prefs_key : prefs_keys) { - String val = prefs.get(prefs_key, null); - if (val != null) - p.setProperty(prefs_key, val); + .doPrivileged((PrivilegedAction) () -> { + Properties p = new Properties(); + String notePath = "/com/sun/media/sound/softsynthesizer"; + try { + Preferences prefroot = Preferences.userRoot(); + if (prefroot.nodeExists(notePath)) { + Preferences prefs = prefroot.node(notePath); + String[] prefs_keys = prefs.keys(); + for (String prefs_key : prefs_keys) { + String val = prefs.get(prefs_key, null); + if (val != null) { + p.setProperty(prefs_key, val); } } - } catch (BackingStoreException e) { - } catch (SecurityException e) { } - return p; + } catch (final BackingStoreException ignored) { } + return p; }); } @@ -1044,7 +1040,6 @@ return; } synchronized (control_mutex) { - Throwable causeException = null; try { if (line != null) { // can throw IllegalArgumentException @@ -1117,24 +1112,17 @@ weakstream.sourceDataLine = sourceDataLine; } - } catch (LineUnavailableException e) { - causeException = e; - } catch (IllegalArgumentException e) { - causeException = e; - } catch (SecurityException e) { - causeException = e; - } - - if (causeException != null) { - if (isOpen()) + } catch (final LineUnavailableException | SecurityException + | IllegalArgumentException e) { + if (isOpen()) { close(); + } // am: need MidiUnavailableException(Throwable) ctor! MidiUnavailableException ex = new MidiUnavailableException( "Can not open line"); - ex.initCause(causeException); + ex.initCause(e); throw ex; } - } } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/com/sun/media/sound/StandardMidiFileReader.java --- a/jdk/src/java.desktop/share/classes/com/sun/media/sound/StandardMidiFileReader.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/com/sun/media/sound/StandardMidiFileReader.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -25,27 +25,25 @@ package com.sun.media.sound; +import java.io.BufferedInputStream; import java.io.DataInputStream; +import java.io.EOFException; import java.io.File; import java.io.FileInputStream; +import java.io.IOException; import java.io.InputStream; -import java.io.IOException; -import java.io.EOFException; -import java.io.BufferedInputStream; import java.net.URL; -import javax.sound.midi.MidiFileFormat; import javax.sound.midi.InvalidMidiDataException; import javax.sound.midi.MetaMessage; import javax.sound.midi.MidiEvent; +import javax.sound.midi.MidiFileFormat; import javax.sound.midi.MidiMessage; import javax.sound.midi.Sequence; import javax.sound.midi.SysexMessage; import javax.sound.midi.Track; import javax.sound.midi.spi.MidiFileReader; - - /** * MIDI file reader. * @@ -53,19 +51,23 @@ * @author Jan Borgersen * @author Florian Bomers */ - public final class StandardMidiFileReader extends MidiFileReader { private static final int MThd_MAGIC = 0x4d546864; // 'MThd' private static final int bisBufferSize = 1024; // buffer size in buffered input streams - public MidiFileFormat getMidiFileFormat(InputStream stream) throws InvalidMidiDataException, IOException { + public MidiFileFormat getMidiFileFormat(InputStream stream) + throws InvalidMidiDataException, IOException { return getMidiFileFormatFromStream(stream, MidiFileFormat.UNKNOWN_LENGTH, null); } - // $$fb 2002-04-17: part of fix for 4635286: MidiSystem.getMidiFileFormat() returns format having invalid length - private MidiFileFormat getMidiFileFormatFromStream(InputStream stream, int fileLength, SMFParser smfParser) throws InvalidMidiDataException, IOException { + // $$fb 2002-04-17: part of fix for 4635286: MidiSystem.getMidiFileFormat() + // returns format having invalid length + private MidiFileFormat getMidiFileFormatFromStream(InputStream stream, + int fileLength, + SMFParser smfParser) + throws InvalidMidiDataException, IOException{ int maxReadLength = 16; int duration = MidiFileFormat.UNKNOWN_LENGTH; DataInputStream dis; @@ -230,7 +232,7 @@ //============================================================================================================= /** - * State variables during parsing of a MIDI file + * State variables during parsing of a MIDI file. */ final class SMFParser { private static final int MTrk_MAGIC = 0x4d54726b; // 'MTrk' @@ -297,7 +299,11 @@ } } // now read track in a byte array - trackData = new byte[trackLength]; + try { + trackData = new byte[trackLength]; + } catch (final OutOfMemoryError oom) { + throw new IOException("Track length too big", oom); + } try { // $$fb 2003-08-20: fix for 4910986: MIDI file parser breaks up on http connection stream.readFully(trackData); @@ -386,8 +392,13 @@ // meta int metaType = readUnsigned(); int metaLength = (int) readVarInt(); + final byte[] metaData; + try { + metaData = new byte[metaLength]; + } catch (final OutOfMemoryError oom) { + throw new IOException("Meta length too big", oom); + } - byte[] metaData = new byte[metaLength]; read(metaData); MetaMessage metaMessage = new MetaMessage(); @@ -413,5 +424,4 @@ throw new EOFException("invalid MIDI file"); } } - } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/java/awt/datatransfer/Clipboard.java --- a/jdk/src/java.desktop/share/classes/java/awt/datatransfer/Clipboard.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/java/awt/datatransfer/Clipboard.java Tue Aug 19 10:32:16 2014 -0700 @@ -25,7 +25,7 @@ package java.awt.datatransfer; -import java.awt.EventQueue; +import sun.datatransfer.DataFlavorUtil; import java.util.Objects; import java.util.Set; @@ -130,7 +130,8 @@ this.contents = contents; if (oldOwner != null && oldOwner != owner) { - EventQueue.invokeLater(() -> oldOwner.lostOwnership(Clipboard.this, oldContents)); + DataFlavorUtil.getDesktopService().invokeOnEventThread(() -> + oldOwner.lostOwnership(Clipboard.this, oldContents)); } fireFlavorsChanged(); } @@ -324,7 +325,7 @@ return; } flavorListeners.forEach(listener -> - EventQueue.invokeLater(() -> + DataFlavorUtil.getDesktopService().invokeOnEventThread(() -> listener.flavorsChanged(new FlavorEvent(Clipboard.this)))); } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/java/awt/datatransfer/DataFlavor.java --- a/jdk/src/java.desktop/share/classes/java/awt/datatransfer/DataFlavor.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/java/awt/datatransfer/DataFlavor.java Tue Aug 19 10:32:16 2014 -0700 @@ -25,7 +25,7 @@ package java.awt.datatransfer; -import sun.awt.datatransfer.DataTransferer; +import sun.datatransfer.DataFlavorUtil; import sun.reflect.misc.ReflectUtil; import java.io.ByteArrayInputStream; @@ -44,7 +44,6 @@ import java.nio.CharBuffer; import java.util.Arrays; import java.util.Collections; -import java.util.Comparator; import java.util.Objects; import static sun.security.util.SecurityConstants.GET_CLASSLOADER_PERMISSION; @@ -582,12 +581,12 @@ } else { params += representationClass.getName(); } - if (DataTransferer.isFlavorCharsetTextType(this) && + if (DataFlavorUtil.isFlavorCharsetTextType(this) && (isRepresentationClassInputStream() || isRepresentationClassByteBuffer() || byte[].class.equals(representationClass))) { - params += ";charset=" + DataTransferer.getTextCharset(this); + params += ";charset=" + DataFlavorUtil.getTextCharset(this); } return params; } @@ -609,13 +608,8 @@ * @since 1.3 */ public static final DataFlavor getTextPlainUnicodeFlavor() { - String encoding = null; - DataTransferer transferer = DataTransferer.getInstance(); - if (transferer != null) { - encoding = transferer.getDefaultUnicodeEncoding(); - } return new DataFlavor( - "text/plain;charset="+encoding + "text/plain;charset=" + DataFlavorUtil.getDesktopService().getDefaultUnicodeEncoding() +";class=java.io.InputStream", "Plain Text"); } @@ -741,12 +735,8 @@ return null; } - if (textFlavorComparator == null) { - textFlavorComparator = new TextFlavorComparator(); - } - DataFlavor bestFlavor = Collections.max(Arrays.asList(availableFlavors), - textFlavorComparator); + DataFlavorUtil.getTextFlavorComparator()); if (!bestFlavor.isFlavorTextType()) { return null; @@ -755,46 +745,6 @@ return bestFlavor; } - private static Comparator textFlavorComparator; - - static class TextFlavorComparator - extends DataTransferer.DataFlavorComparator { - - /** - * Compares two DataFlavor objects. Returns a negative - * integer, zero, or a positive integer as the first - * DataFlavor is worse than, equal to, or better than the - * second. - *

- * DataFlavors are ordered according to the rules outlined - * for selectBestTextFlavor. - * - * @param flavor1 the first DataFlavor to be compared - * @param flavor2 the second DataFlavor to be compared - * @return a negative integer, zero, or a positive integer as the first - * argument is worse, equal to, or better than the second - * @throws ClassCastException if either of the arguments is not an - * instance of DataFlavor - * @throws NullPointerException if either of the arguments is - * null - * - * @see #selectBestTextFlavor - */ - public int compare(DataFlavor flavor1, DataFlavor flavor2) { - if (flavor1.isFlavorTextType()) { - if (flavor2.isFlavorTextType()) { - return super.compare(flavor1, flavor2); - } else { - return 1; - } - } else if (flavor2.isFlavorTextType()) { - return -1; - } else { - return 0; - } - } - } - /** * Gets a Reader for a text flavor, decoded, if necessary, for the expected * charset (encoding). The supported representation classes are @@ -1015,13 +965,13 @@ } if ("text".equals(getPrimaryType())) { - if (DataTransferer.doesSubtypeSupportCharset(this) + if (DataFlavorUtil.doesSubtypeSupportCharset(this) && representationClass != null && !isStandardTextRepresentationClass()) { String thisCharset = - DataTransferer.canonicalName(this.getParameter("charset")); + DataFlavorUtil.canonicalName(this.getParameter("charset")); String thatCharset = - DataTransferer.canonicalName(that.getParameter("charset")); + DataFlavorUtil.canonicalName(that.getParameter("charset")); if (!Objects.equals(thisCharset, thatCharset)) { return false; } @@ -1088,10 +1038,10 @@ // subTypes is '*', regardless of the other subType. if ("text".equals(primaryType)) { - if (DataTransferer.doesSubtypeSupportCharset(this) + if (DataFlavorUtil.doesSubtypeSupportCharset(this) && representationClass != null && !isStandardTextRepresentationClass()) { - String charset = DataTransferer.canonicalName(getParameter("charset")); + String charset = DataFlavorUtil.canonicalName(getParameter("charset")); if (charset != null) { total += charset.hashCode(); } @@ -1280,9 +1230,8 @@ * Returns true if the representation class is Remote. * @return true if the representation class is Remote */ - public boolean isRepresentationClassRemote() { - return DataTransferer.isRemote(representationClass); + return DataFlavorUtil.RMI.isRemote(representationClass); } /** @@ -1356,8 +1305,8 @@ * @since 1.4 */ public boolean isFlavorTextType() { - return (DataTransferer.isFlavorCharsetTextType(this) || - DataTransferer.isFlavorNoncharsetTextType(this)); + return (DataFlavorUtil.isFlavorCharsetTextType(this) || + DataFlavorUtil.isFlavorNoncharsetTextType(this)); } /** diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/java/awt/datatransfer/SystemFlavorMap.java --- a/jdk/src/java.desktop/share/classes/java/awt/datatransfer/SystemFlavorMap.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/java/awt/datatransfer/SystemFlavorMap.java Tue Aug 19 10:32:16 2014 -0700 @@ -25,22 +25,15 @@ package java.awt.datatransfer; -import java.awt.Toolkit; - -import java.io.BufferedInputStream; -import java.io.InputStream; -import java.lang.ref.SoftReference; +import sun.datatransfer.DataFlavorUtil; +import sun.datatransfer.DesktopDatatransferService; import java.io.BufferedReader; -import java.io.File; +import java.io.IOException; +import java.io.InputStream; import java.io.InputStreamReader; -import java.io.IOException; - -import java.net.URL; -import java.net.MalformedURLException; - +import java.lang.ref.SoftReference; import java.util.ArrayList; -import java.util.Arrays; import java.util.Collections; import java.util.HashMap; import java.util.HashSet; @@ -48,12 +41,8 @@ import java.util.List; import java.util.Map; import java.util.Objects; -import java.util.Properties; import java.util.Set; -import sun.awt.AppContext; -import sun.awt.datatransfer.DataTransferer; - /** * The SystemFlavorMap is a configurable map between "natives" (Strings), which * correspond to platform-specific data formats, and "flavors" (DataFlavors), @@ -74,13 +63,6 @@ private static final Object FLAVOR_MAP_KEY = new Object(); /** - * Copied from java.util.Properties. - */ - private static final String keyValueSeparators = "=: \t\r\n\f"; - private static final String strictKeyValueSeparators = "=:"; - private static final String whiteSpaceChars = " \t\r\n\f"; - - /** * The list of valid, decoded text flavor representation classes, in order * from best to worst. */ @@ -198,16 +180,11 @@ /** * Returns the default FlavorMap for this thread's ClassLoader. + * * @return the default FlavorMap for this thread's ClassLoader */ public static FlavorMap getDefaultFlavorMap() { - AppContext context = AppContext.getAppContext(); - FlavorMap fm = (FlavorMap) context.get(FLAVOR_MAP_KEY); - if (fm == null) { - fm = new SystemFlavorMap(); - context.put(FLAVOR_MAP_KEY, fm); - } - return fm; + return DataFlavorUtil.getDesktopService().getFlavorMap(SystemFlavorMap::new); } private SystemFlavorMap() { @@ -223,7 +200,7 @@ } isMapInitialized = true; - InputStream is = SystemFlavorMap.class.getResourceAsStream("/sun/awt/datatransfer/flavormap.properties"); + InputStream is = SystemFlavorMap.class.getResourceAsStream("/sun/datatransfer/resources/flavormap.properties"); if (is == null) { throw new InternalError("Default flavor mapping not found"); } @@ -238,22 +215,25 @@ line = line.substring(0, line.length() - 1) + reader.readLine().trim(); } int delimiterPosition = line.indexOf('='); - String key = line.substring(0, delimiterPosition).replace("\\ ", " "); + String key = line.substring(0, delimiterPosition).replaceAll("\\ ", " "); String[] values = line.substring(delimiterPosition + 1, line.length()).split(","); for (String value : values) { try { + value = loadConvert(value); MimeType mime = new MimeType(value); if ("text".equals(mime.getPrimaryType())) { String charset = mime.getParameter("charset"); - if (DataTransferer.doesSubtypeSupportCharset(mime.getSubType(), charset)) + if (DataFlavorUtil.doesSubtypeSupportCharset(mime.getSubType(), charset)) { // We need to store the charset and eoln // parameters, if any, so that the // DataTransferer will have this information // for conversion into the native format. - DataTransferer transferer = DataTransferer.getInstance(); - if (transferer != null) { - transferer.registerTextFlavorProperties(key, charset, + DesktopDatatransferService desktopService = + DataFlavorUtil.getDesktopService(); + if (desktopService.isDesktopPresent()) { + desktopService.registerTextFlavorProperties( + key, charset, mime.getParameter("eoln"), mime.getParameter("terminators")); } @@ -305,6 +285,63 @@ } } + // Copied from java.util.Properties + private static String loadConvert(String theString) { + char aChar; + int len = theString.length(); + StringBuilder outBuffer = new StringBuilder(len); + + for (int x = 0; x < len; ) { + aChar = theString.charAt(x++); + if (aChar == '\\') { + aChar = theString.charAt(x++); + if (aChar == 'u') { + // Read the xxxx + int value = 0; + for (int i = 0; i < 4; i++) { + aChar = theString.charAt(x++); + switch (aChar) { + case '0': case '1': case '2': case '3': case '4': + case '5': case '6': case '7': case '8': case '9': { + value = (value << 4) + aChar - '0'; + break; + } + case 'a': case 'b': case 'c': + case 'd': case 'e': case 'f': { + value = (value << 4) + 10 + aChar - 'a'; + break; + } + case 'A': case 'B': case 'C': + case 'D': case 'E': case 'F': { + value = (value << 4) + 10 + aChar - 'A'; + break; + } + default: { + throw new IllegalArgumentException( + "Malformed \\uxxxx encoding."); + } + } + } + outBuffer.append((char)value); + } else { + if (aChar == 't') { + aChar = '\t'; + } else if (aChar == 'r') { + aChar = '\r'; + } else if (aChar == 'n') { + aChar = '\n'; + } else if (aChar == 'f') { + aChar = '\f'; + } + outBuffer.append(aChar); + } + } else { + outBuffer.append(aChar); + } + } + return outBuffer.toString(); + } + /** * Stores the listed object under the specified hash key in map. Unlike a * standard map, the listed object will not replace any object already at @@ -332,10 +369,10 @@ LinkedHashSet flavors = getNativeToFlavor().get(nat); if (nat != null && !disabledMappingGenerationKeys.contains(nat)) { - DataTransferer transferer = DataTransferer.getInstance(); - if (transferer != null) { + DesktopDatatransferService desktopService = DataFlavorUtil.getDesktopService(); + if (desktopService.isDesktopPresent()) { LinkedHashSet platformFlavors = - transferer.getPlatformMappingsForNative(nat); + desktopService.getPlatformMappingsForNative(nat); if (!platformFlavors.isEmpty()) { if (flavors != null) { // Prepending the platform-specific mappings ensures @@ -395,10 +432,10 @@ LinkedHashSet natives = getFlavorToNative().get(flav); if (flav != null && !disabledMappingGenerationKeys.contains(flav)) { - DataTransferer transferer = DataTransferer.getInstance(); - if (transferer != null) { + DesktopDatatransferService desktopService = DataFlavorUtil.getDesktopService(); + if (desktopService.isDesktopPresent()) { LinkedHashSet platformNatives = - transferer.getPlatformMappingsForFlavor(flav); + desktopService.getPlatformMappingsForFlavor(flav); if (!platformNatives.isEmpty()) { if (natives != null) { // Prepend the platform-specific mappings to ensure @@ -474,7 +511,7 @@ // In this case we shouldn't synthesize a native for this flavor, // since its mappings were explicitly specified. retval = flavorToNativeLookup(flav, false); - } else if (DataTransferer.isFlavorCharsetTextType(flav)) { + } else if (DataFlavorUtil.isFlavorCharsetTextType(flav)) { retval = new LinkedHashSet<>(0); // For text/* flavors, flavor-to-native mappings specified in @@ -502,7 +539,7 @@ // addUnencodedNativeForFlavor(), so they have lower priority. retval.addAll(flavorToNativeLookup(flav, false)); } - } else if (DataTransferer.isFlavorNoncharsetTextType(flav)) { + } else if (DataFlavorUtil.isFlavorNoncharsetTextType(flav)) { retval = getTextTypeToNative().get(flav.mimeType.getBaseType()); if (retval == null || retval.isEmpty()) { @@ -602,7 +639,7 @@ // on load from flavormap.properties. } - if (DataTransferer.doesSubtypeSupportCharset(subType, null)) { + if (DataFlavorUtil.doesSubtypeSupportCharset(subType, null)) { if (TEXT_PLAIN_BASE_TYPE.equals(baseType)) { returnValue.add(DataFlavor.stringFlavor); @@ -624,7 +661,7 @@ } } - for (String charset : DataTransferer.standardEncodings()) { + for (String charset : DataFlavorUtil.standardEncodings()) { for (String encodedTextClass : ENCODED_TEXT_CLASSES) { final String mimeType = diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/java/awt/font/TextLayout.java --- a/jdk/src/java.desktop/share/classes/java/awt/font/TextLayout.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/java/awt/font/TextLayout.java Tue Aug 19 10:32:16 2014 -0700 @@ -1811,7 +1811,7 @@ * should be logical or visual counterparts. They are not * checked for validity. */ - private final TextHitInfo getStrongHit(TextHitInfo hit1, TextHitInfo hit2) { + private TextHitInfo getStrongHit(TextHitInfo hit1, TextHitInfo hit2) { // right now we're using the following rule for strong hits: // A hit on a character with a lower level diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/java/beans/PropertyChangeSupport.java --- a/jdk/src/java.desktop/share/classes/java/beans/PropertyChangeSupport.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/java/beans/PropertyChangeSupport.java Tue Aug 19 10:32:16 2014 -0700 @@ -544,7 +544,7 @@ /** * {@inheritDoc} */ - public final PropertyChangeListener extract(PropertyChangeListener listener) { + public PropertyChangeListener extract(PropertyChangeListener listener) { while (listener instanceof PropertyChangeListenerProxy) { listener = ((PropertyChangeListenerProxy) listener).getListener(); } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/java/beans/VetoableChangeSupport.java --- a/jdk/src/java.desktop/share/classes/java/beans/VetoableChangeSupport.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/java/beans/VetoableChangeSupport.java Tue Aug 19 10:32:16 2014 -0700 @@ -533,7 +533,7 @@ /** * {@inheritDoc} */ - public final VetoableChangeListener extract(VetoableChangeListener listener) { + public VetoableChangeListener extract(VetoableChangeListener listener) { while (listener instanceof VetoableChangeListenerProxy) { listener = ((VetoableChangeListenerProxy) listener).getListener(); } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/midi/ControllerEventListener.java --- a/jdk/src/java.desktop/share/classes/javax/sound/midi/ControllerEventListener.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/ControllerEventListener.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2002, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -27,38 +27,35 @@ import java.util.EventListener; - /** - * The ControllerEventListener interface should be implemented - * by classes whose instances need to be notified when a Sequencer - * has processed a requested type of MIDI control-change event. - * To register a ControllerEventListener object to receive such - * notifications, invoke the + * The {@code ControllerEventListener} interface should be implemented by + * classes whose instances need to be notified when a {@link Sequencer} has + * processed a requested type of MIDI control-change event. To register a + * {@code ControllerEventListener} object to receive such notifications, invoke + * the * {@link Sequencer#addControllerEventListener(ControllerEventListener, int[]) - * addControllerEventListener} method of Sequencer, - * specifying the types of MIDI controllers about which you are interested in - * getting control-change notifications. - * - * @see MidiChannel#controlChange(int, int) + * addControllerEventListener} method of {@code Sequencer}, specifying the types + * of MIDI controllers about which you are interested in getting control-change + * notifications. * * @author Kara Kytle + * @see MidiChannel#controlChange(int, int) */ public interface ControllerEventListener extends EventListener { /** - * Invoked when a Sequencer has encountered and processed - * a control-change event of interest to this listener. The event passed - * in is a ShortMessage whose first data byte indicates - * the controller number and whose second data byte is the value to which - * the controller was set. + * Invoked when a {@link Sequencer} has encountered and processed a + * control-change event of interest to this listener. The event passed in is + * a {@code ShortMessage} whose first data byte indicates the controller + * number and whose second data byte is the value to which the controller + * was set. * - * @param event the control-change event that the sequencer encountered in - * the sequence it is processing - * + * @param event the control-change event that the sequencer encountered in + * the sequence it is processing * @see Sequencer#addControllerEventListener(ControllerEventListener, int[]) * @see MidiChannel#controlChange(int, int) * @see ShortMessage#getData1 * @see ShortMessage#getData2 */ - public void controlChange(ShortMessage event); + void controlChange(ShortMessage event); } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/midi/Instrument.java --- a/jdk/src/java.desktop/share/classes/javax/sound/midi/Instrument.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/Instrument.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2004, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -25,49 +25,41 @@ package javax.sound.midi; -import java.net.URL; - - - /** - * An instrument is a sound-synthesis algorithm with certain parameter - * settings, usually designed to emulate a specific real-world - * musical instrument or to achieve a specific sort of sound effect. - * Instruments are typically stored in collections called soundbanks. - * Before the instrument can be used to play notes, it must first be loaded - * onto a synthesizer, and then it must be selected for use on - * one or more channels, via a program-change command. MIDI notes - * that are subsequently received on those channels will be played using + * An instrument is a sound-synthesis algorithm with certain parameter settings, + * usually designed to emulate a specific real-world musical instrument or to + * achieve a specific sort of sound effect. Instruments are typically stored in + * collections called soundbanks. Before the instrument can be used to play + * notes, it must first be loaded onto a synthesizer, and then it must be + * selected for use on one or more channels, via a program-change command. MIDI + * notes that are subsequently received on those channels will be played using * the sound of the selected instrument. * + * @author Kara Kytle * @see Soundbank * @see Soundbank#getInstruments * @see Patch * @see Synthesizer#loadInstrument(Instrument) * @see MidiChannel#programChange(int, int) - * @author Kara Kytle */ - public abstract class Instrument extends SoundbankResource { - /** - * Instrument patch + * Instrument patch. */ private final Patch patch; - /** - * Constructs a new MIDI instrument from the specified Patch. - * When a subsequent request is made to load the - * instrument, the sound bank will search its contents for this instrument's Patch, - * and the instrument will be loaded into the synthesizer at the - * bank and program location indicated by the Patch object. - * @param soundbank sound bank containing the instrument - * @param patch the patch of this instrument - * @param name the name of this instrument - * @param dataClass the class used to represent the sample's data. + * Constructs a new MIDI instrument from the specified {@code Patch}. When a + * subsequent request is made to load the instrument, the sound bank will + * search its contents for this instrument's {@code Patch}, and the + * instrument will be loaded into the synthesizer at the bank and program + * location indicated by the {@code Patch} object. * + * @param soundbank sound bank containing the instrument + * @param patch the patch of this instrument + * @param name the name of this instrument + * @param dataClass the class used to represent the sample's data * @see Synthesizer#loadInstrument(Instrument) */ protected Instrument(Soundbank soundbank, Patch patch, String name, Class dataClass) { @@ -76,10 +68,10 @@ this.patch = patch; } - /** - * Obtains the Patch object that indicates the bank and program + * Obtains the {@code Patch} object that indicates the bank and program * numbers where this instrument is to be stored in the synthesizer. + * * @return this instrument's patch */ public Patch getPatch() { diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/midi/InvalidMidiDataException.java --- a/jdk/src/java.desktop/share/classes/javax/sound/midi/InvalidMidiDataException.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/InvalidMidiDataException.java Tue Aug 19 10:32:16 2014 -0700 @@ -25,25 +25,25 @@ package javax.sound.midi; - /** - * An InvalidMidiDataException indicates that inappropriate MIDI - * data was encountered. This often means that the data is invalid in and of - * itself, from the perspective of the MIDI specification. An example would - * be an undefined status byte. However, the exception might simply - * mean that the data was invalid in the context it was used, or that - * the object to which the data was given was unable to parse or use it. - * For example, a file reader might not be able to parse a Type 2 MIDI file, even - * though that format is defined in the MIDI specification. + * An {@code InvalidMidiDataException} indicates that inappropriate MIDI data + * was encountered. This often means that the data is invalid in and of itself, + * from the perspective of the MIDI specification. An example would be an + * undefined status byte. However, the exception might simply mean that the data + * was invalid in the context it was used, or that the object to which the data + * was given was unable to parse or use it. For example, a file reader might not + * be able to parse a Type 2 MIDI file, even though that format is defined in + * the MIDI specification. * * @author Kara Kytle */ public class InvalidMidiDataException extends Exception { + private static final long serialVersionUID = 2780771756789932067L; /** - * Constructs an InvalidMidiDataException with - * null for its error detail message. + * Constructs an {@code InvalidMidiDataException} with {@code null} for its + * error detail message. */ public InvalidMidiDataException() { @@ -51,10 +51,10 @@ } /** - * Constructs an InvalidMidiDataException with the - * specified detail message. + * Constructs an {@code InvalidMidiDataException} with the specified detail + * message. * - * @param message the string to display as an error detail message + * @param message the string to display as an error detail message */ public InvalidMidiDataException(String message) { diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/midi/MetaEventListener.java --- a/jdk/src/java.desktop/share/classes/javax/sound/midi/MetaEventListener.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/MetaEventListener.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2002, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -27,24 +27,23 @@ import java.util.EventListener; - /** - * The MetaEventListener interface should be implemented - * by classes whose instances need to be notified when a {@link Sequencer} - * has processed a {@link MetaMessage}. - * To register a MetaEventListener object to receive such - * notifications, pass it as the argument to the - * {@link Sequencer#addMetaEventListener(MetaEventListener) addMetaEventListener} - * method of Sequencer. + * The {@code MetaEventListener} interface should be implemented by classes + * whose instances need to be notified when a {@link Sequencer} has processed a + * {@link MetaMessage}. To register a {@code MetaEventListener} object to + * receive such notifications, pass it as the argument to the + * {@link Sequencer#addMetaEventListener(MetaEventListener) + * addMetaEventListener} method of {@code Sequencer}. * * @author Kara Kytle */ public interface MetaEventListener extends EventListener { /** - * Invoked when a {@link Sequencer} has encountered and processed - * a MetaMessage in the {@link Sequence} it is processing. - * @param meta the meta-message that the sequencer encountered + * Invoked when a {@link Sequencer} has encountered and processed a + * {@code MetaMessage} in the {@code Sequence} it is processing. + * + * @param meta the meta-message that the sequencer encountered */ - public void meta(MetaMessage meta); + void meta(MetaMessage meta); } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/midi/MetaMessage.java --- a/jdk/src/java.desktop/share/classes/javax/sound/midi/MetaMessage.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/MetaMessage.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -25,65 +25,54 @@ package javax.sound.midi; - /** - * A MetaMessage is a {@link MidiMessage} that is not meaningful to synthesizers, but - * that can be stored in a MIDI file and interpreted by a sequencer program. - * (See the discussion in the MidiMessage - * class description.) The Standard MIDI Files specification defines - * various types of meta-events, such as sequence number, lyric, cue point, - * and set tempo. There are also meta-events - * for such information as lyrics, copyrights, tempo indications, time and key - * signatures, markers, etc. For more information, see the Standard MIDI Files 1.0 - * specification, which is part of the Complete MIDI 1.0 Detailed Specification - * published by the MIDI Manufacturer's Association + * A {@code MetaMessage} is a {@link MidiMessage} that is not meaningful to + * synthesizers, but that can be stored in a MIDI file and interpreted by a + * sequencer program. (See the discussion in the {@code MidiMessage} class + * description.) The Standard MIDI Files specification defines various types of + * meta-events, such as sequence number, lyric, cue point, and set tempo. There + * are also meta-events for such information as lyrics, copyrights, tempo + * indications, time and key signatures, markers, etc. For more information, see + * the Standard MIDI Files 1.0 specification, which is part of the Complete MIDI + * 1.0 Detailed Specification published by the MIDI Manufacturer's Association * (http://www.midi.org). - * *

- * When data is being transported using MIDI wire protocol, - * a {@link ShortMessage} with the status value 0xFF represents - * a system reset message. In MIDI files, this same status value denotes a MetaMessage. - * The types of meta-message are distinguished from each other by the first byte - * that follows the status byte 0xFF. The subsequent bytes are data - * bytes. As with system exclusive messages, there are an arbitrary number of - * data bytes, depending on the type of MetaMessage. - * - * @see MetaEventListener + * When data is being transported using MIDI wire protocol, a + * {@link ShortMessage} with the status value {@code 0xFF} represents a system + * reset message. In MIDI files, this same status value denotes a + * {@code MetaMessage}. The types of meta-message are distinguished from each + * other by the first byte that follows the status byte {@code 0xFF}. The + * subsequent bytes are data bytes. As with system exclusive messages, there are + * an arbitrary number of data bytes, depending on the type of + * {@code MetaMessage}. * * @author David Rivas * @author Kara Kytle + * @see MetaEventListener */ - public class MetaMessage extends MidiMessage { - - // Status byte defines - /** - * Status byte for MetaMessage (0xFF, or 255), which is used - * in MIDI files. It has the same value as SYSTEM_RESET, which - * is used in the real-time "MIDI wire" protocol. + * Status byte for {@code MetaMessage} (0xFF, or 255), which is used in MIDI + * files. It has the same value as SYSTEM_RESET, which is used in the + * real-time "MIDI wire" protocol. + * * @see MidiMessage#getStatus */ public static final int META = 0xFF; // 255 - // Instance variables - /** - * The length of the actual message in the data array. - * This is used to determine how many bytes of the data array - * is the message, and how many are the status byte, the - * type byte, and the variable-length-int describing the - * length of the message. + * The length of the actual message in the data array. This is used to + * determine how many bytes of the data array is the message, and how many + * are the status byte, the type byte, and the variable-length-int + * describing the length of the message. */ private int dataLength = 0; - /** - * Constructs a new MetaMessage. The contents of - * the message are not set here; use - * {@link #setMessage(int, byte[], int) setMessage} - * to set them subsequently. + * Constructs a new {@code MetaMessage}. The contents of the message are not + * set here; use {@link #setMessage(int, byte[], int) setMessage} to set + * them subsequently. */ public MetaMessage() { // Default meta message data: just the META status byte value @@ -91,17 +80,17 @@ } /** - * Constructs a new {@code MetaMessage} and sets the message parameters. - * The contents of the message can be changed by using - * the {@code setMessage} method. + * Constructs a new {@code MetaMessage} and sets the message parameters. The + * contents of the message can be changed by using the {@code setMessage} + * method. * - * @param type meta-message type (must be less than 128) - * @param data the data bytes in the MIDI message - * @param length an amount of bytes in the {@code data} byte array; - * it should be non-negative and less than or equal to - * {@code data.length} - * @throws InvalidMidiDataException if the parameter values do not specify - * a valid MIDI meta message + * @param type meta-message type (must be less than 128) + * @param data the data bytes in the MIDI message + * @param length an amount of bytes in the {@code data} byte array; it + * should be non-negative and less than or equal to + * {@code data.length} + * @throws InvalidMidiDataException if the parameter values do not specify a + * valid MIDI meta message * @see #setMessage(int, byte[], int) * @see #getType() * @see #getData() @@ -113,12 +102,11 @@ setMessage(type, data, length); // can throw InvalidMidiDataException } - /** - * Constructs a new MetaMessage. - * @param data an array of bytes containing the complete message. - * The message data may be changed using the setMessage - * method. + * Constructs a new {@code MetaMessage}. + * + * @param data an array of bytes containing the complete message. The + * message data may be changed using the {@code setMessage} method. * @see #setMessage */ protected MetaMessage(byte[] data) { @@ -133,24 +121,24 @@ } } - /** - * Sets the message parameters for a MetaMessage. - * Since only one status byte value, 0xFF, is allowed for meta-messages, - * it does not need to be specified here. Calls to {@link MidiMessage#getStatus getStatus} return - * 0xFF for all meta-messages. + * Sets the message parameters for a {@code MetaMessage}. Since only one + * status byte value, {@code 0xFF}, is allowed for meta-messages, it does + * not need to be specified here. Calls to + * {@link MidiMessage#getStatus getStatus} return {@code 0xFF} for all + * meta-messages. *

- * The type argument should be a valid value for the byte that - * follows the status byte in the MetaMessage. The data argument - * should contain all the subsequent bytes of the MetaMessage. In other words, - * the byte that specifies the type of MetaMessage is not considered a data byte. + * The {@code type} argument should be a valid value for the byte that + * follows the status byte in the {@code MetaMessage}. The {@code data} + * argument should contain all the subsequent bytes of the + * {@code MetaMessage}. In other words, the byte that specifies the type of + * {@code MetaMessage} is not considered a data byte. * - * @param type meta-message type (must be less than 128) - * @param data the data bytes in the MIDI message - * @param length the number of bytes in the data - * byte array - * @throws InvalidMidiDataException if the - * parameter values do not specify a valid MIDI meta message + * @param type meta-message type (must be less than 128) + * @param data the data bytes in the MIDI message + * @param length the number of bytes in the {@code data} byte array + * @throws InvalidMidiDataException if the parameter values do not specify a + * valid MIDI meta message */ public void setMessage(int type, byte[] data, int length) throws InvalidMidiDataException { @@ -172,10 +160,10 @@ } } - /** - * Obtains the type of the MetaMessage. - * @return an integer representing the MetaMessage type + * Obtains the type of the {@code MetaMessage}. + * + * @return an integer representing the {@code MetaMessage} type */ public int getType() { if (length>=2) { @@ -184,16 +172,15 @@ return 0; } - - /** - * Obtains a copy of the data for the meta message. The returned - * array of bytes does not include the status byte or the message - * length data. The length of the data for the meta message is - * the length of the array. Note that the length of the entire - * message includes the status byte and the meta message type - * byte, and therefore may be longer than the returned array. - * @return array containing the meta message data. + * Obtains a copy of the data for the meta message. The returned array of + * bytes does not include the status byte or the message length data. The + * length of the data for the meta message is the length of the array. Note + * that the length of the entire message includes the status byte and the + * meta message type byte, and therefore may be longer than the returned + * array. + * + * @return array containing the meta message data * @see MidiMessage#getLength */ public byte[] getData() { @@ -202,10 +189,10 @@ return returnedArray; } - /** - * Creates a new object of the same class and with the same contents - * as this object. + * Creates a new object of the same class and with the same contents as this + * object. + * * @return a clone of this instance */ public Object clone() { @@ -240,5 +227,4 @@ } data[off] = (byte) (value & mask); } - } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/midi/MidiChannel.java --- a/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiChannel.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiChannel.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1998, 2004, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -25,513 +25,450 @@ package javax.sound.midi; - /** - * A MidiChannel object represents a single MIDI channel. - * Generally, each MidiChannel method processes a like-named MIDI - * "channel voice" or "channel mode" message as defined by the MIDI specification. However, - * MidiChannel adds some "get" methods that retrieve the value - * most recently set by one of the standard MIDI channel messages. Similarly, - * methods for per-channel solo and mute have been added. + * A {@code MidiChannel} object represents a single MIDI channel. Generally, + * each {@code MidiChannel} method processes a like-named MIDI "channel voice" + * or "channel mode" message as defined by the MIDI specification. However, + * {@code MidiChannel} adds some "get" methods that retrieve the value most + * recently set by one of the standard MIDI channel messages. Similarly, methods + * for per-channel solo and mute have been added. *

- * A {@link Synthesizer} object has a collection - * of MidiChannels, usually one for each of the 16 channels - * prescribed by the MIDI 1.0 specification. The Synthesizer - * generates sound when its MidiChannels receive - * noteOn messages. + * A {@link Synthesizer} object has a collection of {@code MidiChannels}, + * usually one for each of the 16 channels prescribed by the MIDI 1.0 + * specification. The {@code Synthesizer} generates sound when its + * {@code MidiChannels} receive {@code noteOn} messages. *

* See the MIDI 1.0 Specification for more information about the prescribed - * behavior of the MIDI channel messages, which are not exhaustively - * documented here. The specification is titled MIDI Reference: - * The Complete MIDI 1.0 Detailed Specification, and is published by - * the MIDI Manufacturer's Association ( - * http://www.midi.org). + * behavior of the MIDI channel messages, which are not exhaustively documented + * here. The specification is titled + * {@code MIDI Reference: The Complete MIDI 1.0 Detailed Specification}, and is + * published by the MIDI Manufacturer's Association + * (http://www.midi.org). *

* MIDI was originally a protocol for reporting the gestures of a keyboard - * musician. This genesis is visible in the MidiChannel API, which + * musician. This genesis is visible in the {@code MidiChannel} API, which * preserves such MIDI concepts as key number, key velocity, and key pressure. * It should be understood that the MIDI data does not necessarily originate * with a keyboard player (the source could be a different kind of musician, or - * software). Some devices might generate constant values for velocity - * and pressure, regardless of how the note was performed. - * Also, the MIDI specification often leaves it up to the - * synthesizer to use the data in the way the implementor sees fit. For - * example, velocity data need not always be mapped to volume and/or brightness. - * - * @see Synthesizer#getChannels + * software). Some devices might generate constant values for velocity and + * pressure, regardless of how the note was performed. Also, the MIDI + * specification often leaves it up to the synthesizer to use the data in the + * way the implementor sees fit. For example, velocity data need not always be + * mapped to volume and/or brightness. * * @author David Rivas * @author Kara Kytle + * @see Synthesizer#getChannels */ - public interface MidiChannel { /** - * Starts the specified note sounding. The key-down velocity - * usually controls the note's volume and/or brightness. - * If velocity is zero, this method instead acts like - * {@link #noteOff(int)}, terminating the note. + * Starts the specified note sounding. The key-down velocity usually + * controls the note's volume and/or brightness. If {@code velocity} is + * zero, this method instead acts like {@link #noteOff(int)}, terminating + * the note. * - * @param noteNumber the MIDI note number, from 0 to 127 (60 = Middle C) - * @param velocity the speed with which the key was depressed - * + * @param noteNumber the MIDI note number, from 0 to 127 (60 = Middle C) + * @param velocity the speed with which the key was depressed * @see #noteOff(int, int) */ - public void noteOn(int noteNumber, int velocity); + void noteOn(int noteNumber, int velocity); /** - * Turns the specified note off. The key-up velocity, if not ignored, can - * be used to affect how quickly the note decays. - * In any case, the note might not die away instantaneously; its decay - * rate is determined by the internals of the Instrument. - * If the Hold Pedal (a controller; see - * {@link #controlChange(int, int) controlChange}) - * is down, the effect of this method is deferred until the pedal is - * released. + * Turns the specified note off. The key-up velocity, if not ignored, can be + * used to affect how quickly the note decays. In any case, the note might + * not die away instantaneously; its decay rate is determined by the + * internals of the {@code Instrument}. If the Hold Pedal (a controller; see + * {@link #controlChange(int, int) controlChange}) is down, the effect of + * this method is deferred until the pedal is released. * - * - * @param noteNumber the MIDI note number, from 0 to 127 (60 = Middle C) - * @param velocity the speed with which the key was released - * + * @param noteNumber the MIDI note number, from 0 to 127 (60 = Middle C) + * @param velocity the speed with which the key was released * @see #noteOff(int) * @see #noteOn * @see #allNotesOff * @see #allSoundOff */ - public void noteOff(int noteNumber, int velocity); + void noteOff(int noteNumber, int velocity); /** * Turns the specified note off. * - * @param noteNumber the MIDI note number, from 0 to 127 (60 = Middle C) - * + * @param noteNumber the MIDI note number, from 0 to 127 (60 = Middle C) * @see #noteOff(int, int) */ - public void noteOff(int noteNumber); + void noteOff(int noteNumber); /** - * Reacts to a change in the specified note's key pressure. - * Polyphonic key pressure - * allows a keyboard player to press multiple keys simultaneously, each - * with a different amount of pressure. The pressure, if not ignored, - * is typically used to vary such features as the volume, brightness, - * or vibrato of the note. + * Reacts to a change in the specified note's key pressure. Polyphonic key + * pressure allows a keyboard player to press multiple keys simultaneously, + * each with a different amount of pressure. The pressure, if not ignored, + * is typically used to vary such features as the volume, brightness, or + * vibrato of the note. + *

+ * It is possible that the underlying synthesizer does not support this MIDI + * message. In order to verify that {@code setPolyPressure} was successful, + * use {@code getPolyPressure}. * - * It is possible that the underlying synthesizer - * does not support this MIDI message. In order - * to verify that setPolyPressure - * was successful, use getPolyPressure. - * - * @param noteNumber the MIDI note number, from 0 to 127 (60 = Middle C) - * @param pressure value for the specified key, from 0 to 127 (127 = - * maximum pressure) - * + * @param noteNumber the MIDI note number, from 0 to 127 (60 = Middle C) + * @param pressure value for the specified key, from 0 to 127 + * (127 = maximum pressure) * @see #getPolyPressure(int) */ - public void setPolyPressure(int noteNumber, int pressure); + void setPolyPressure(int noteNumber, int pressure); /** * Obtains the pressure with which the specified key is being depressed. - * - * @param noteNumber the MIDI note number, from 0 to 127 (60 = Middle C) + *

+ * If the device does not support setting poly pressure, this method always + * returns 0. Calling {@code setPolyPressure} will have no effect then. * - * If the device does not support setting poly pressure, - * this method always returns 0. Calling - * setPolyPressure will have no effect then. - * + * @param noteNumber the MIDI note number, from 0 to 127 (60 = Middle C) * @return the amount of pressure for that note, from 0 to 127 - * (127 = maximum pressure) - * + * (127 = maximum pressure) * @see #setPolyPressure(int, int) */ - public int getPolyPressure(int noteNumber); + int getPolyPressure(int noteNumber); /** - * Reacts to a change in the keyboard pressure. Channel - * pressure indicates how hard the keyboard player is depressing - * the entire keyboard. This can be the maximum or - * average of the per-key pressure-sensor values, as set by - * setPolyPressure. More commonly, it is a measurement of - * a single sensor on a device that doesn't implement polyphonic key - * pressure. Pressure can be used to control various aspects of the sound, - * as described under {@link #setPolyPressure(int, int) setPolyPressure}. + * Reacts to a change in the keyboard pressure. Channel pressure indicates + * how hard the keyboard player is depressing the entire keyboard. This can + * be the maximum or average of the per-key pressure-sensor values, as set + * by {@code setPolyPressure}. More commonly, it is a measurement of a + * single sensor on a device that doesn't implement polyphonic key pressure. + * Pressure can be used to control various aspects of the sound, as + * described under {@link #setPolyPressure(int, int) setPolyPressure}. + *

+ * It is possible that the underlying synthesizer does not support this MIDI + * message. In order to verify that {@code setChannelPressure} was + * successful, use {@code getChannelPressure}. * - * It is possible that the underlying synthesizer - * does not support this MIDI message. In order - * to verify that setChannelPressure - * was successful, use getChannelPressure. - * - * @param pressure the pressure with which the keyboard is being depressed, - * from 0 to 127 (127 = maximum pressure) + * @param pressure the pressure with which the keyboard is being depressed, + * from 0 to 127 (127 = maximum pressure) * @see #setPolyPressure(int, int) * @see #getChannelPressure */ - public void setChannelPressure(int pressure); + void setChannelPressure(int pressure); /** * Obtains the channel's keyboard pressure. - * If the device does not support setting channel pressure, - * this method always returns 0. Calling - * setChannelPressure will have no effect then. + *

+ * If the device does not support setting channel pressure, this method + * always returns 0. Calling {@code setChannelPressure} will have no effect + * then. * - * @return the amount of pressure for that note, - * from 0 to 127 (127 = maximum pressure) - * + * @return the amount of pressure for that note, from 0 to 127 + * (127 = maximum pressure) * @see #setChannelPressure(int) */ - public int getChannelPressure(); + int getChannelPressure(); /** - * Reacts to a change in the specified controller's value. A controller - * is some control other than a keyboard key, such as a - * switch, slider, pedal, wheel, or breath-pressure sensor. - * The MIDI 1.0 Specification provides standard numbers for typical - * controllers on MIDI devices, and describes the intended effect - * for some of the controllers. - * The way in which an - * Instrument reacts to a controller change may be - * specific to the Instrument. + * Reacts to a change in the specified controller's value. A controller is + * some control other than a keyboard key, such as a switch, slider, pedal, + * wheel, or breath-pressure sensor. The MIDI 1.0 Specification provides + * standard numbers for typical controllers on MIDI devices, and describes + * the intended effect for some of the controllers. The way in which an + * {@code Instrument} reacts to a controller change may be specific to the + * {@code Instrument}. *

- * The MIDI 1.0 Specification defines both 7-bit controllers - * and 14-bit controllers. Continuous controllers, such - * as wheels and sliders, typically have 14 bits (two MIDI bytes), - * while discrete controllers, such as switches, typically have 7 bits - * (one MIDI byte). Refer to the specification to see the - * expected resolution for each type of control. + * The MIDI 1.0 Specification defines both 7-bit controllers and 14-bit + * controllers. Continuous controllers, such as wheels and sliders, + * typically have 14 bits (two MIDI bytes), while discrete controllers, such + * as switches, typically have 7 bits (one MIDI byte). Refer to the + * specification to see the expected resolution for each type of control. *

- * Controllers 64 through 95 (0x40 - 0x5F) allow 7-bit precision. - * The value of a 7-bit controller is set completely by the - * value argument. An additional set of controllers - * provide 14-bit precision by using two controller numbers, one - * for the most significant 7 bits and another for the least significant - * 7 bits. Controller numbers 0 through 31 (0x00 - 0x1F) control the - * most significant 7 bits of 14-bit controllers; controller numbers - * 32 through 63 (0x20 - 0x3F) control the least significant 7 bits of - * these controllers. For example, controller number 7 (0x07) controls - * the upper 7 bits of the channel volume controller, and controller - * number 39 (0x27) controls the lower 7 bits. - * The value of a 14-bit controller is determined - * by the interaction of the two halves. When the most significant 7 bits - * of a controller are set (using controller numbers 0 through 31), the - * lower 7 bits are automatically set to 0. The corresponding controller - * number for the lower 7 bits may then be used to further modulate the - * controller value. + * Controllers 64 through 95 (0x40 - 0x5F) allow 7-bit precision. The value + * of a 7-bit controller is set completely by the {@code value} argument. An + * additional set of controllers provide 14-bit precision by using two + * controller numbers, one for the most significant 7 bits and another for + * the least significant 7 bits. Controller numbers 0 through 31 + * (0x00 - 0x1F) control the most significant 7 bits of 14-bit controllers; + * controller numbers 32 through 63 (0x20 - 0x3F) control the least + * significant 7 bits of these controllers. For example, controller number 7 + * (0x07) controls the upper 7 bits of the channel volume controller, and + * controller number 39 (0x27) controls the lower 7 bits. The value of a + * 14-bit controller is determined by the interaction of the two halves. + * When the most significant 7 bits of a controller are set (using + * controller numbers 0 through 31), the lower 7 bits are automatically set + * to 0. The corresponding controller number for the lower 7 bits may then + * be used to further modulate the controller value. + *

+ * It is possible that the underlying synthesizer does not support a + * specific controller message. In order to verify that a call to + * {@code controlChange} was successful, use {@code getController}. * - * It is possible that the underlying synthesizer - * does not support a specific controller message. In order - * to verify that a call to controlChange - * was successful, use getController. - * - * @param controller the controller number (0 to 127; see the MIDI - * 1.0 Specification for the interpretation) - * @param value the value to which the specified controller is changed (0 to 127) - * + * @param controller the controller number (0 to 127; see the MIDI 1.0 + * Specification for the interpretation) + * @param value the value to which the specified controller is changed + * (0 to 127) * @see #getController(int) */ - public void controlChange(int controller, int value); + void controlChange(int controller, int value); /** - * Obtains the current value of the specified controller. The return - * value is represented with 7 bits. For 14-bit controllers, the MSB and - * LSB controller value needs to be obtained separately. For example, - * the 14-bit value of the volume controller can be calculated by - * multiplying the value of controller 7 (0x07, channel volume MSB) - * with 128 and adding the - * value of controller 39 (0x27, channel volume LSB). + * Obtains the current value of the specified controller. The return value + * is represented with 7 bits. For 14-bit controllers, the MSB and LSB + * controller value needs to be obtained separately. For example, the 14-bit + * value of the volume controller can be calculated by multiplying the value + * of controller 7 (0x07, channel volume MSB) with 128 and adding the value + * of controller 39 (0x27, channel volume LSB). + *

+ * If the device does not support setting a specific controller, this method + * returns 0 for that controller. Calling {@code controlChange} will have no + * effect then. * - * If the device does not support setting a specific controller, - * this method returns 0 for that controller. - * Calling controlChange will have no effect then. - * - * @param controller the number of the controller whose value is desired. - * The allowed range is 0-127; see the MIDI - * 1.0 Specification for the interpretation. - * + * @param controller the number of the controller whose value is desired. + * The allowed range is 0-127; see the MIDI 1.0 Specification for + * the interpretation. * @return the current value of the specified controller (0 to 127) - * * @see #controlChange(int, int) */ - public int getController(int controller); + int getController(int controller); /** - * Changes a program (patch). This selects a specific - * instrument from the currently selected bank of instruments. + * Changes a program (patch). This selects a specific instrument from the + * currently selected bank of instruments. *

- * The MIDI specification does not - * dictate whether notes that are already sounding should switch - * to the new instrument (timbre) or continue with their original timbre - * until terminated by a note-off. + * The MIDI specification does not dictate whether notes that are already + * sounding should switch to the new instrument (timbre) or continue with + * their original timbre until terminated by a note-off. *

- * The program number is zero-based (expressed from 0 to 127). - * Note that MIDI hardware displays and literature about MIDI - * typically use the range 1 to 128 instead. + * The program number is zero-based (expressed from 0 to 127). Note that + * MIDI hardware displays and literature about MIDI typically use the range + * 1 to 128 instead. + *

+ * It is possible that the underlying synthesizer does not support a + * specific program. In order to verify that a call to {@code programChange} + * was successful, use {@code getProgram}. * - * It is possible that the underlying synthesizer - * does not support a specific program. In order - * to verify that a call to programChange - * was successful, use getProgram. - * - * @param program the program number to switch to (0 to 127) - * + * @param program the program number to switch to (0 to 127) * @see #programChange(int, int) * @see #getProgram() */ - public void programChange(int program); + void programChange(int program); /** * Changes the program using bank and program (patch) numbers. - * - * It is possible that the underlying synthesizer - * does not support a specific bank, or program. In order - * to verify that a call to programChange - * was successful, use getProgram and - * getController. - * Since banks are changed by way of control changes, - * you can verify the current bank with the following - * statement: + *

+ * It is possible that the underlying synthesizer does not support a + * specific bank, or program. In order to verify that a call to + * {@code programChange} was successful, use {@code getProgram} and + * {@code getController}. Since banks are changed by way of control changes, + * you can verify the current bank with the following statement: * 

-     *   int bank = (getController(0) * 128)
-     *              + getController(32);
+     *   int bank = (getController(0) * 128) + getController(32);
      *
* - * @param bank the bank number to switch to (0 to 16383) - * @param program the program (patch) to use in the specified bank (0 to 127) + * @param bank the bank number to switch to (0 to 16383) + * @param program the program (patch) to use in the specified bank + * (0 to 127) * @see #programChange(int) * @see #getProgram() */ - public void programChange(int bank, int program); + void programChange(int bank, int program); /** * Obtains the current program number for this channel. + * * @return the program number of the currently selected patch * @see Patch#getProgram * @see Synthesizer#loadInstrument * @see #programChange(int) */ - public int getProgram(); + int getProgram(); /** - * Changes the pitch offset for all notes on this channel. - * This affects all currently sounding notes as well as subsequent ones. - * (For pitch bend to cease, the value needs to be reset to the - * center position.) - *

The MIDI specification - * stipulates that pitch bend be a 14-bit value, where zero - * is maximum downward bend, 16383 is maximum upward bend, and - * 8192 is the center (no pitch bend). The actual - * amount of pitch change is not specified; it can be changed by - * a pitch-bend sensitivity setting. However, the General MIDI - * specification says that the default range should be two semitones - * up and down from center. + * Changes the pitch offset for all notes on this channel. This affects all + * currently sounding notes as well as subsequent ones. (For pitch bend to + * cease, the value needs to be reset to the center position.) + *

+ * The MIDI specification stipulates that pitch bend be a 14-bit value, + * where zero is maximum downward bend, 16383 is maximum upward bend, and + * 8192 is the center (no pitch bend). The actual amount of pitch change is + * not specified; it can be changed by a pitch-bend sensitivity setting. + * However, the General MIDI specification says that the default range + * should be two semitones up and down from center. + *

+ * It is possible that the underlying synthesizer does not support this MIDI + * message. In order to verify that {@code setPitchBend} was successful, use + * {@code getPitchBend}. * - * It is possible that the underlying synthesizer - * does not support this MIDI message. In order - * to verify that setPitchBend - * was successful, use getPitchBend. - * - * @param bend the amount of pitch change, as a nonnegative 14-bit value - * (8192 = no bend) - * + * @param bend the amount of pitch change, as a nonnegative 14-bit value + * (8192 = no bend) * @see #getPitchBend */ - public void setPitchBend(int bend); + void setPitchBend(int bend); /** - * Obtains the upward or downward pitch offset for this channel. - * If the device does not support setting pitch bend, - * this method always returns 8192. Calling - * setPitchBend will have no effect then. + * Obtains the upward or downward pitch offset for this channel. If the + * device does not support setting pitch bend, this method always returns + * 8192. Calling {@code setPitchBend} will have no effect then. * * @return bend amount, as a nonnegative 14-bit value (8192 = no bend) - * * @see #setPitchBend(int) */ - public int getPitchBend(); + int getPitchBend(); /** * Resets all the implemented controllers to their default values. * * @see #controlChange(int, int) */ - public void resetAllControllers(); + void resetAllControllers(); /** - * Turns off all notes that are currently sounding on this channel. - * The notes might not die away instantaneously; their decay - * rate is determined by the internals of the Instrument. - * If the Hold Pedal controller (see - * {@link #controlChange(int, int) controlChange}) - * is down, the effect of this method is deferred until the pedal is - * released. + * Turns off all notes that are currently sounding on this channel. The + * notes might not die away instantaneously; their decay rate is determined + * by the internals of the {@code Instrument}. If the Hold Pedal controller + * (see {@link #controlChange(int, int) controlChange}) is down, the effect + * of this method is deferred until the pedal is released. * * @see #allSoundOff * @see #noteOff(int) */ - public void allNotesOff(); + void allNotesOff(); /** * Immediately turns off all sounding notes on this channel, ignoring the * state of the Hold Pedal and the internal decay rate of the current - * Instrument. + * {@code Instrument}. * * @see #allNotesOff */ - public void allSoundOff(); + void allSoundOff(); /** - * Turns local control on or off. The default is for local control - * to be on. The "on" setting means that if a device is capable - * of both synthesizing sound and transmitting MIDI messages, - * it will synthesize sound in response to the note-on and - * note-off messages that it itself transmits. It will also respond - * to messages received from other transmitting devices. - * The "off" setting means that the synthesizer will ignore its - * own transmitted MIDI messages, but not those received from other devices. + * Turns local control on or off. The default is for local control to be on. + * The "on" setting means that if a device is capable of both synthesizing + * sound and transmitting MIDI messages, it will synthesize sound in + * response to the note-on and note-off messages that it itself transmits. + * It will also respond to messages received from other transmitting + * devices. The "off" setting means that the synthesizer will ignore its own + * transmitted MIDI messages, but not those received from other devices. + *

+ * It is possible that the underlying synthesizer does not support local + * control. In order to verify that a call to {@code localControl} was + * successful, check the return value. * - * It is possible that the underlying synthesizer - * does not support local control. In order - * to verify that a call to localControl - * was successful, check the return value. - * - * @param on true to turn local control on, false - * to turn local control off - * @return the new local-control value, or false - * if local control is not supported - * + * @param on {@code true} to turn local control on, {@code false} to turn + * local control off + * @return the new local-control value, or false if local control is not + * supported */ - public boolean localControl(boolean on); + boolean localControl(boolean on); /** - * Turns mono mode on or off. In mono mode, the channel synthesizes - * only one note at a time. In poly mode (identical to mono mode off), - * the channel can synthesize multiple notes simultaneously. - * The default is mono off (poly mode on). + * Turns mono mode on or off. In mono mode, the channel synthesizes only one + * note at a time. In poly mode (identical to mono mode off), the channel + * can synthesize multiple notes simultaneously. The default is mono off + * (poly mode on). *

- * "Mono" is short for the word "monophonic," which in this context - * is opposed to the word "polyphonic" and refers to a single synthesizer - * voice per MIDI channel. It - * has nothing to do with how many audio channels there might be - * (as in "monophonic" versus "stereophonic" recordings). + * "Mono" is short for the word "monophonic," which in this context is + * opposed to the word "polyphonic" and refers to a single synthesizer voice + * per MIDI channel. It has nothing to do with how many audio channels there + * might be (as in "monophonic" versus "stereophonic" recordings). + *

+ * It is possible that the underlying synthesizer does not support mono + * mode. In order to verify that a call to {@code setMono} was successful, + * use {@code getMono}. * - * It is possible that the underlying synthesizer - * does not support mono mode. In order - * to verify that a call to setMono - * was successful, use getMono. - * - * @param on true to turn mono mode on, false to - * turn it off (which means turning poly mode on). - * + * @param on {@code true} to turn mono mode on, {@code false} to turn it + * off (which means turning poly mode on) * @see #getMono * @see VoiceStatus */ - public void setMono(boolean on); + void setMono(boolean on); /** - * Obtains the current mono/poly mode. - * Synthesizers that do not allow changing mono/poly mode - * will always return the same value, regardless - * of calls to setMono. - * @return true if mono mode is on, otherwise - * false (meaning poly mode is on). + * Obtains the current mono/poly mode. Synthesizers that do not allow + * changing mono/poly mode will always return the same value, regardless of + * calls to {@code setMono}. * + * @return {@code true} if mono mode is on, otherwise {@code false} (meaning + * poly mode is on) * @see #setMono(boolean) */ - public boolean getMono(); + boolean getMono(); /** - * Turns omni mode on or off. In omni mode, the channel responds - * to messages sent on all channels. When omni is off, the channel - * responds only to messages sent on its channel number. - * The default is omni off. + * Turns omni mode on or off. In omni mode, the channel responds to messages + * sent on all channels. When omni is off, the channel responds only to + * messages sent on its channel number. The default is omni off. + *

+ * It is possible that the underlying synthesizer does not support omni + * mode. In order to verify that {@code setOmni} was successful, use + * {@code getOmni}. * - * It is possible that the underlying synthesizer - * does not support omni mode. In order - * to verify that setOmni - * was successful, use getOmni. - * - * @param on true to turn omni mode on, false to - * turn it off. - * + * @param on {@code true} to turn omni mode on, {@code false} to turn it + * off * @see #getOmni * @see VoiceStatus */ - public void setOmni(boolean on); + void setOmni(boolean on); /** - * Obtains the current omni mode. - * Synthesizers that do not allow changing the omni mode - * will always return the same value, regardless - * of calls to setOmni. - * @return true if omni mode is on, otherwise - * false (meaning omni mode is off). + * Obtains the current omni mode. Synthesizers that do not allow changing + * the omni mode will always return the same value, regardless of calls to + * {@code setOmni}. * + * @return {@code true} if omni mode is on, otherwise {@code false} (meaning + * omni mode is off) * @see #setOmni(boolean) */ - public boolean getOmni(); + boolean getOmni(); /** - * Sets the mute state for this channel. A value of - * true means the channel is to be muted, false - * means the channel can sound (if other channels are not soloed). + * Sets the mute state for this channel. A value of {@code true} means the + * channel is to be muted, {@code false} means the channel can sound (if + * other channels are not soloed). *

- * Unlike {@link #allSoundOff()}, this method - * applies to only a specific channel, not to all channels. Further, it - * silences not only currently sounding notes, but also subsequently - * received notes. + * Unlike {@link #allSoundOff()}, this method applies to only a specific + * channel, not to all channels. Further, it silences not only currently + * sounding notes, but also subsequently received notes. + *

+ * It is possible that the underlying synthesizer does not support muting + * channels. In order to verify that a call to {@code setMute} was + * successful, use {@code getMute}. * - * It is possible that the underlying synthesizer - * does not support muting channels. In order - * to verify that a call to setMute - * was successful, use getMute. - * - * @param mute the new mute state - * + * @param mute the new mute state * @see #getMute * @see #setSolo(boolean) */ - public void setMute(boolean mute); + void setMute(boolean mute); /** - * Obtains the current mute state for this channel. - * If the underlying synthesizer does not support - * muting this channel, this method always returns - * false. + * Obtains the current mute state for this channel. If the underlying + * synthesizer does not support muting this channel, this method always + * returns {@code false}. * - * @return true the channel is muted, - * or false if not - * + * @return {@code true} the channel is muted, or {@code false} if not * @see #setMute(boolean) */ - public boolean getMute(); + boolean getMute(); /** - * Sets the solo state for this channel. - * If solo is true only this channel - * and other soloed channels will sound. If solo - * is false then only other soloed channels will - * sound, unless no channels are soloed, in which case all - * unmuted channels will sound. + * Sets the solo state for this channel. If {@code solo} is {@code true} + * only this channel and other soloed channels will sound. If {@code solo} + * is {@code false} then only other soloed channels will sound, unless no + * channels are soloed, in which case all unmuted channels will sound. + *

+ * It is possible that the underlying synthesizer does not support solo + * channels. In order to verify that a call to {@code setSolo} was + * successful, use {@code getSolo}. * - * It is possible that the underlying synthesizer - * does not support solo channels. In order - * to verify that a call to setSolo - * was successful, use getSolo. - * - * @param soloState new solo state for the channel + * @param soloState new solo state for the channel * @see #getSolo() */ - public void setSolo(boolean soloState); + void setSolo(boolean soloState); /** - * Obtains the current solo state for this channel. - * If the underlying synthesizer does not support - * solo on this channel, this method always returns - * false. + * Obtains the current solo state for this channel. If the underlying + * synthesizer does not support solo on this channel, this method always + * returns {@code false}. * - * @return true the channel is solo, - * or false if not - * + * @return {@code true} the channel is solo, or {@code false} if not * @see #setSolo(boolean) */ - public boolean getSolo(); + boolean getSolo(); } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/midi/MidiDevice.java --- a/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiDevice.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiDevice.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -27,64 +27,52 @@ import java.util.List; - /** - * MidiDevice is the base interface for all MIDI devices. - * Common devices include synthesizers, sequencers, MIDI input ports, and MIDI - * output ports. - * - *

A MidiDevice can be a transmitter or a receiver of - * MIDI events, or both. Therefore, it can provide {@link Transmitter} - * or {@link Receiver} instances (or both). Typically, MIDI IN ports - * provide transmitters, MIDI OUT ports and synthesizers provide - * receivers. A Sequencer typically provides transmitters for playback - * and receivers for recording. - * - *

A MidiDevice can be opened and closed explicitly as - * well as implicitly. Explicit opening is accomplished by calling - * {@link #open}, explicit closing is done by calling {@link - * #close} on the MidiDevice instance. - * If an application opens a MidiDevice - * explicitly, it has to close it explicitly to free system resources - * and enable the application to exit cleanly. Implicit opening is - * done by calling {@link javax.sound.midi.MidiSystem#getReceiver - * MidiSystem.getReceiver} and {@link - * javax.sound.midi.MidiSystem#getTransmitter - * MidiSystem.getTransmitter}. The MidiDevice used by - * MidiSystem.getReceiver and - * MidiSystem.getTransmitter is implementation-dependant - * unless the properties javax.sound.midi.Receiver - * and javax.sound.midi.Transmitter are used (see the - * description of properties to select default providers in - * {@link javax.sound.midi.MidiSystem}). A MidiDevice - * that was opened implicitly, is closed implicitly by closing the - * Receiver or Transmitter that resulted in - * opening it. If more than one implicitly opening - * Receiver or Transmitter were obtained by - * the application, the device is closed after the last - * Receiver or Transmitter has been - * closed. On the other hand, calling getReceiver or - * getTransmitter on the device instance directly does - * not open the device implicitly. Closing these - * Transmitters and Receivers does not close - * the device implicitly. To use a device with Receivers - * or Transmitters obtained this way, the device has to - * be opened and closed explicitly. - * - *

If implicit and explicit opening and closing are mixed on the - * same MidiDevice instance, the following rules apply: +/** + * {@code MidiDevice} is the base interface for all MIDI devices. Common devices + * include synthesizers, sequencers, MIDI input ports, and MIDI output ports. + *

+ * A {@code MidiDevice} can be a transmitter or a receiver of MIDI events, or + * both. Therefore, it can provide {@link Transmitter} or {@link Receiver} + * instances (or both). Typically, MIDI IN ports provide transmitters, MIDI OUT + * ports and synthesizers provide receivers. A Sequencer typically provides + * transmitters for playback and receivers for recording. + *

+ * A {@code MidiDevice} can be opened and closed explicitly as well as + * implicitly. Explicit opening is accomplished by calling {@link #open}, + * explicit closing is done by calling {@link #close} on the {@code MidiDevice} + * instance. If an application opens a {@code MidiDevice} explicitly, it has to + * close it explicitly to free system resources and enable the application to + * exit cleanly. Implicit opening is done by calling + * {@link MidiSystem#getReceiver} and {@link MidiSystem#getTransmitter}. The + * {@code MidiDevice} used by {@code MidiSystem.getReceiver} and + * {@code MidiSystem.getTransmitter} is implementation-dependant unless the + * properties {@code javax.sound.midi.Receiver} and + * {@code javax.sound.midi.Transmitter} are used (see the description of + * properties to select default providers in {@link MidiSystem}). A + * {@code MidiDevice} that was opened implicitly, is closed implicitly by + * closing the {@code Receiver} or {@code Transmitter} that resulted in opening + * it. If more than one implicitly opening {@code Receiver} or + * {@code Transmitter} were obtained by the application, the device is closed + * after the last {@code Receiver} or {@code Transmitter} has been closed. On + * the other hand, calling {@code getReceiver} or {@code getTransmitter} on the + * device instance directly does not open the device implicitly. Closing these + * {@code Transmitter}s and {@code Receiver}s does not close the device + * implicitly. To use a device with {@code Receiver}s or {@code Transmitter}s + * obtained this way, the device has to be opened and closed explicitly. + *

+ * If implicit and explicit opening and closing are mixed on the same + * {@code MidiDevice} instance, the following rules apply: * *

    - *
  • After an explicit open (either before or after implicit - * opens), the device will not be closed by implicit closing. The only - * way to close an explicitly opened device is an explicit close.
    • - * - *
  • An explicit close always closes the device, even if it also has - * been opened implicitly. A subsequent implicit close has no further - * effect.
    • + *
  • After an explicit open (either before or after implicit opens), the + * device will not be closed by implicit closing. The only way to close an + * explicitly opened device is an explicit close.
    • + *
  • An explicit close always closes the device, even if it also has been + * opened implicitly. A subsequent implicit close has no further effect.
    • *
* - * To detect if a MidiDevice represents a hardware MIDI port, the - * following programming technique can be used: + * To detect if a MidiDevice represents a hardware MIDI port, the following + * programming technique can be used: * * 
{@code
  * MidiDevice device = ...;
@@ -95,193 +83,171 @@
  * }
* *

- * A MidiDevice includes a {@link MidiDevice.Info} object - * to provide manufacturer information and so on. + * A {@code MidiDevice} includes a {@link Info} object to provide manufacturer + * information and so on. * + * @author Kara Kytle + * @author Florian Bomers * @see Synthesizer * @see Sequencer * @see Receiver * @see Transmitter - * - * @author Kara Kytle - * @author Florian Bomers */ - public interface MidiDevice extends AutoCloseable { - /** * Obtains information about the device, including its Java class and - * Strings containing its name, vendor, and description. + * {@code Strings} containing its name, vendor, and description. * * @return device info */ - public Info getDeviceInfo(); - + Info getDeviceInfo(); /** - * Opens the device, indicating that it should now acquire any - * system resources it requires and become operational. - * - *

An application opening a device explicitly with this call - * has to close the device by calling {@link #close}. This is - * necessary to release system resources and allow applications to - * exit cleanly. - * + * Opens the device, indicating that it should now acquire any system + * resources it requires and become operational. + *

+ * An application opening a device explicitly with this call has to close + * the device by calling {@link #close}. This is necessary to release system + * resources and allow applications to exit cleanly. *

- * Note that some devices, once closed, cannot be reopened. Attempts - * to reopen such a device will always result in a MidiUnavailableException. + * Note that some devices, once closed, cannot be reopened. Attempts to + * reopen such a device will always result in a MidiUnavailableException. * - * @throws MidiUnavailableException thrown if the device cannot be - * opened due to resource restrictions. - * @throws SecurityException thrown if the device cannot be - * opened due to security restrictions. - * + * @throws MidiUnavailableException thrown if the device cannot be opened + * due to resource restrictions + * @throws SecurityException thrown if the device cannot be opened due to + * security restrictions * @see #close * @see #isOpen */ - public void open() throws MidiUnavailableException; - + void open() throws MidiUnavailableException; /** - * Closes the device, indicating that the device should now release - * any system resources it is using. - * - *

All Receiver and Transmitter instances - * open from this device are closed. This includes instances retrieved - * via MidiSystem. + * Closes the device, indicating that the device should now release any + * system resources it is using. + *

+ * All {@code Receiver} and {@code Transmitter} instances open from this + * device are closed. This includes instances retrieved via + * {@code MidiSystem}. * * @see #open * @see #isOpen */ - public void close(); - + void close(); /** * Reports whether the device is open. * - * @return true if the device is open, otherwise - * false + * @return {@code true} if the device is open, otherwise {@code false} * @see #open * @see #close */ - public boolean isOpen(); - + boolean isOpen(); /** - * Obtains the current time-stamp of the device, in microseconds. - * If a device supports time-stamps, it should start counting at - * 0 when the device is opened and continue incrementing its - * time-stamp in microseconds until the device is closed. - * If it does not support time-stamps, it should always return - * -1. - * @return the current time-stamp of the device in microseconds, - * or -1 if time-stamping is not supported by the device. + * Obtains the current time-stamp of the device, in microseconds. If a + * device supports time-stamps, it should start counting at 0 when the + * device is opened and continue incrementing its time-stamp in microseconds + * until the device is closed. If it does not support time-stamps, it should + * always return -1. + * + * @return the current time-stamp of the device in microseconds, or -1 if + * time-stamping is not supported by the device */ - public long getMicrosecondPosition(); - + long getMicrosecondPosition(); /** - * Obtains the maximum number of MIDI IN connections available on this - * MIDI device for receiving MIDI data. - * @return maximum number of MIDI IN connections, - * or -1 if an unlimited number of connections is available. + * Obtains the maximum number of MIDI IN connections available on this MIDI + * device for receiving MIDI data. + * + * @return maximum number of MIDI IN connections, or -1 if an unlimited + * number of connections is available */ - public int getMaxReceivers(); - + int getMaxReceivers(); /** - * Obtains the maximum number of MIDI OUT connections available on this - * MIDI device for transmitting MIDI data. - * @return maximum number of MIDI OUT connections, - * or -1 if an unlimited number of connections is available. + * Obtains the maximum number of MIDI OUT connections available on this MIDI + * device for transmitting MIDI data. + * + * @return maximum number of MIDI OUT connections, or -1 if an unlimited + * number of connections is available */ - public int getMaxTransmitters(); - + int getMaxTransmitters(); /** - * Obtains a MIDI IN receiver through which the MIDI device may receive - * MIDI data. The returned receiver must be closed when the application - * has finished using it. - * - *

Usually the returned receiver implements - * the {@code MidiDeviceReceiver} interface. + * Obtains a MIDI IN receiver through which the MIDI device may receive MIDI + * data. The returned receiver must be closed when the application has + * finished using it. + *

+ * Usually the returned receiver implements the {@code MidiDeviceReceiver} + * interface. + *

+ * Obtaining a {@code Receiver} with this method does not open the device. + * To be able to use the device, it has to be opened explicitly by calling + * {@link #open}. Also, closing the {@code Receiver} does not close the + * device. It has to be closed explicitly by calling {@link #close}. * - *

Obtaining a Receiver with this method does not - * open the device. To be able to use the device, it has to be - * opened explicitly by calling {@link #open}. Also, closing the - * Receiver does not close the device. It has to be - * closed explicitly by calling {@link #close}. - * - * @return a receiver for the device. + * @return a receiver for the device * @throws MidiUnavailableException thrown if a receiver is not available - * due to resource restrictions + * due to resource restrictions * @see Receiver#close() */ - public Receiver getReceiver() throws MidiUnavailableException; - + Receiver getReceiver() throws MidiUnavailableException; /** - * Returns all currently active, non-closed receivers - * connected with this MidiDevice. - * A receiver can be removed - * from the device by closing it. - * - *

Usually the returned receivers implement - * the {@code MidiDeviceReceiver} interface. + * Returns all currently active, non-closed receivers connected with this + * MidiDevice. A receiver can be removed from the device by closing it. + *

+ * Usually the returned receivers implement the {@code MidiDeviceReceiver} + * interface. * * @return an unmodifiable list of the open receivers * @since 1.5 */ List getReceivers(); - /** * Obtains a MIDI OUT connection from which the MIDI device will transmit - * MIDI data The returned transmitter must be closed when the application + * MIDI data. The returned transmitter must be closed when the application * has finished using it. - * - *

Usually the returned transmitter implements - * the {@code MidiDeviceTransmitter} interface. + *

+ * Usually the returned transmitter implements the + * {@code MidiDeviceTransmitter} interface. + *

+ * Obtaining a {@code Transmitter} with this method does not open the + * device. To be able to use the device, it has to be opened explicitly by + * calling {@link #open}. Also, closing the {@code Transmitter} does not + * close the device. It has to be closed explicitly by calling + * {@link #close}. * - *

Obtaining a Transmitter with this method does not - * open the device. To be able to use the device, it has to be - * opened explicitly by calling {@link #open}. Also, closing the - * Transmitter does not close the device. It has to be - * closed explicitly by calling {@link #close}. - * - * @return a MIDI OUT transmitter for the device. + * @return a MIDI OUT transmitter for the device * @throws MidiUnavailableException thrown if a transmitter is not available - * due to resource restrictions + * due to resource restrictions * @see Transmitter#close() */ - public Transmitter getTransmitter() throws MidiUnavailableException; - + Transmitter getTransmitter() throws MidiUnavailableException; /** - * Returns all currently active, non-closed transmitters - * connected with this MidiDevice. - * A transmitter can be removed - * from the device by closing it. - * - *

Usually the returned transmitters implement - * the {@code MidiDeviceTransmitter} interface. + * Returns all currently active, non-closed transmitters connected with this + * MidiDevice. A transmitter can be removed from the device by closing it. + *

+ * Usually the returned transmitters implement the + * {@code MidiDeviceTransmitter} interface. * * @return an unmodifiable list of the open transmitters * @since 1.5 */ List getTransmitters(); - - /** - * A MidiDevice.Info object contains assorted - * data about a {@link MidiDevice}, including its - * name, the company who created it, and descriptive text. + * A {@code MidiDevice.Info} object contains assorted data about a + * {@link MidiDevice}, including its name, the company who created it, and + * descriptive text. * * @see MidiDevice#getDeviceInfo */ - public static class Info { + class Info { /** * The device's name. @@ -303,16 +269,16 @@ */ private String version; - /** * Constructs a device info object. * - * @param name the name of the device - * @param vendor the name of the company who provides the device - * @param description a description of the device - * @param version version information for the device + * @param name the name of the device + * @param vendor the name of the company who provides the device + * @param description a description of the device + * @param version version information for the device */ - protected Info(String name, String vendor, String description, String version) { + protected Info(String name, String vendor, String description, + String version) { this.name = name; this.vendor = vendor; @@ -320,20 +286,18 @@ this.version = version; } - /** - * Reports whether two objects are equal. - * Returns true if the objects are identical. - * @param obj the reference object with which to compare this - * object - * @return true if this object is the same as the - * obj argument; false otherwise + * Reports whether two objects are equal. Returns {@code true} if the + * objects are identical. + * + * @param obj the reference object with which to compare this object + * @return {@code true} if this object is the same as the {@code obj} + * argument; {@code false} otherwise */ public final boolean equals(Object obj) { return super.equals(obj); } - /** * Finalizes the hashcode method. */ @@ -341,7 +305,6 @@ return super.hashCode(); } - /** * Obtains the name of the device. * @@ -351,43 +314,40 @@ return name; } - /** * Obtains the name of the company who supplies the device. + * * @return device the vendor's name */ public final String getVendor() { return vendor; } - /** * Obtains the description of the device. + * * @return a description of the device */ public final String getDescription() { return description; } - /** * Obtains the version of the device. + * * @return textual version information for the device. */ public final String getVersion() { return version; } - /** * Provides a string representation of the device information. - + * * @return a description of the info object */ public final String toString() { return name; } } // class Info - - } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/midi/MidiDeviceReceiver.java --- a/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiDeviceReceiver.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiDeviceReceiver.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2010, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -26,16 +26,18 @@ package javax.sound.midi; /** - *

{@code MidiDeviceReceiver} is a {@code Receiver} which represents - * a MIDI input connector of a {@code MidiDevice} - * (see {@link MidiDevice#getReceiver()}). + * {@code MidiDeviceReceiver} is a {@code Receiver} which represents a MIDI + * input connector of a {@code MidiDevice} (see + * {@link MidiDevice#getReceiver()}). * * @since 1.7 */ public interface MidiDeviceReceiver extends Receiver { + /** * Obtains a MidiDevice object which is an owner of this Receiver. + * * @return a MidiDevice object which is an owner of this Receiver */ - public MidiDevice getMidiDevice(); + MidiDevice getMidiDevice(); } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/midi/MidiDeviceTransmitter.java --- a/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiDeviceTransmitter.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiDeviceTransmitter.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2010, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -25,11 +25,10 @@ package javax.sound.midi; - /** - *

{@code MidiDeviceTransmitter} is a {@code Transmitter} which represents - * a MIDI input connector of a {@code MidiDevice} - * (see {@link MidiDevice#getTransmitter()}). + * {@code MidiDeviceTransmitter} is a {@code Transmitter} which represents a + * MIDI input connector of a {@code MidiDevice} (see + * {@link MidiDevice#getTransmitter()}). * * @since 1.7 */ @@ -37,7 +36,8 @@ /** * Obtains a MidiDevice object which is an owner of this Transmitter. + * * @return a MidiDevice object which is an owner of this Transmitter */ - public MidiDevice getMidiDevice(); + MidiDevice getMidiDevice(); } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/midi/MidiEvent.java --- a/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiEvent.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiEvent.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2002, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -26,41 +26,35 @@ package javax.sound.midi; /** - * MIDI events contain a MIDI message and a corresponding time-stamp - * expressed in ticks, and can represent the MIDI event information - * stored in a MIDI file or a {@link Sequence} object. The - * duration of a tick is specified by the timing information contained - * in the MIDI file or Sequence object. + * MIDI events contain a MIDI message and a corresponding time-stamp expressed + * in ticks, and can represent the MIDI event information stored in a MIDI file + * or a {@link Sequence} object. The duration of a tick is specified by the + * timing information contained in the MIDI file or {@code Sequence} object. *

- * In Java Sound, MidiEvent objects are typically contained in a - * {@link Track}, and Tracks are likewise - * contained in a Sequence. - * + * In Java Sound, {@code MidiEvent} objects are typically contained in a + * {@link Track}, and {@code Tracks} are likewise contained in a + * {@code Sequence}. * * @author David Rivas * @author Kara Kytle */ public class MidiEvent { - - // Instance variables - /** * The MIDI message for this event. */ private final MidiMessage message; - /** * The tick value for this event. */ private long tick; - /** - * Constructs a new MidiEvent. - * @param message the MIDI message contained in the event - * @param tick the time-stamp for the event, in MIDI ticks + * Constructs a new {@code MidiEvent}. + * + * @param message the MIDI message contained in the event + * @param tick the time-stamp for the event, in MIDI ticks */ public MidiEvent(MidiMessage message, long tick) { @@ -70,24 +64,25 @@ /** * Obtains the MIDI message contained in the event. + * * @return the MIDI message */ public MidiMessage getMessage() { return message; } - /** - * Sets the time-stamp for the event, in MIDI ticks - * @param tick the new time-stamp, in MIDI ticks + * Sets the time-stamp for the event, in MIDI ticks. + * + * @param tick the new time-stamp, in MIDI ticks */ public void setTick(long tick) { this.tick = tick; } - /** - * Obtains the time-stamp for the event, in MIDI ticks + * Obtains the time-stamp for the event, in MIDI ticks. + * * @return the time-stamp for the event, in MIDI ticks */ public long getTick() { diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/midi/MidiFileFormat.java --- a/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiFileFormat.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiFileFormat.java Tue Aug 19 10:32:16 2014 -0700 @@ -25,29 +25,23 @@ package javax.sound.midi; -import java.io.InputStream; -import java.io.IOException; import java.util.Collections; import java.util.HashMap; import java.util.Map; - /** - * A MidiFileFormat object encapsulates a MIDI file's - * type, as well as its length and timing information. - * - *

A MidiFileFormat object can - * include a set of properties. A property is a pair of key and value: - * the key is of type String, the associated property - * value is an arbitrary object. - * Properties specify additional informational - * meta data (like a author, or copyright). - * Properties are optional information, and file reader and file - * writer implementations are not required to provide or - * recognize properties. - * - *

The following table lists some common properties that should - * be used in implementations: + * A {@code MidiFileFormat} object encapsulates a MIDI file's type, as well as + * its length and timing information. + *

+ * A {@code MidiFileFormat} object can include a set of properties. A property + * is a pair of key and value: the key is of type {@code String}, the associated + * property value is an arbitrary object. Properties specify additional + * informational meta data (like a author, or copyright). Properties are + * optional information, and file reader and file writer implementations are not + * required to provide or recognize properties. + *

+ * The following table lists some common properties that should be used in + * implementations: * * @@ -83,24 +77,21 @@ * *
MIDI File Format Properties
* - * @see MidiSystem#getMidiFileFormat(java.io.File) - * @see Sequencer#setSequence(java.io.InputStream stream) - * * @author Kara Kytle * @author Florian Bomers + * @see MidiSystem#getMidiFileFormat(java.io.File) + * @see Sequencer#setSequence(java.io.InputStream stream) */ - public class MidiFileFormat { - /** * Represents unknown length. + * * @see #getByteLength * @see #getMicrosecondLength */ public static final int UNKNOWN_LENGTH = -1; - /** * The type of MIDI file. */ @@ -132,19 +123,22 @@ */ protected long microsecondLength; - - /** The set of properties */ + /** + * The set of properties. + */ private HashMap properties; - /** - * Constructs a MidiFileFormat. + * Constructs a {@code MidiFileFormat}. * - * @param type the MIDI file type (0, 1, or 2) - * @param divisionType the timing division type (PPQ or one of the SMPTE types) - * @param resolution the timing resolution - * @param bytes the length of the MIDI file in bytes, or UNKNOWN_LENGTH if not known - * @param microseconds the duration of the file in microseconds, or UNKNOWN_LENGTH if not known + * @param type the MIDI file type (0, 1, or 2) + * @param divisionType the timing division type (PPQ or one of the SMPTE + * types) + * @param resolution the timing resolution + * @param bytes the length of the MIDI file in bytes, or UNKNOWN_LENGTH if + * not known + * @param microseconds the duration of the file in microseconds, or + * UNKNOWN_LENGTH if not known * @see #UNKNOWN_LENGTH * @see Sequence#PPQ * @see Sequence#SMPTE_24 @@ -162,21 +156,18 @@ this.properties = null; } - /** - * Construct a MidiFileFormat with a set of properties. + * Construct a {@code MidiFileFormat} with a set of properties. * - * @param type the MIDI file type (0, 1, or 2) - * @param divisionType the timing division type - * (PPQ or one of the SMPTE types) - * @param resolution the timing resolution - * @param bytes the length of the MIDI file in bytes, - * or UNKNOWN_LENGTH if not known - * @param microseconds the duration of the file in microseconds, - * or UNKNOWN_LENGTH if not known - * @param properties a Map<String,Object> object - * with properties - * + * @param type the MIDI file type (0, 1, or 2) + * @param divisionType the timing division type (PPQ or one of the SMPTE + * types) + * @param resolution the timing resolution + * @param bytes the length of the MIDI file in bytes, or UNKNOWN_LENGTH if + * not known + * @param microseconds the duration of the file in microseconds, or + * UNKNOWN_LENGTH if not known + * @param properties a {@code Map} object with properties * @see #UNKNOWN_LENGTH * @see Sequence#PPQ * @see Sequence#SMPTE_24 @@ -192,10 +183,9 @@ this.properties = new HashMap(properties); } - - /** * Obtains the MIDI file type. + * * @return the file's type (0, 1, or 2) */ public int getType() { @@ -206,7 +196,6 @@ * Obtains the timing division type for the MIDI file. * * @return the division type (PPQ or one of the SMPTE types) - * * @see Sequence#Sequence(float, int) * @see Sequence#PPQ * @see Sequence#SMPTE_24 @@ -219,11 +208,10 @@ return divisionType; } - /** - * Obtains the timing resolution for the MIDI file. - * If the division type is PPQ, the resolution is specified in ticks per beat. - * For SMTPE timing, the resolution is specified in ticks per frame. + * Obtains the timing resolution for the MIDI file. If the division type is + * PPQ, the resolution is specified in ticks per beat. For SMTPE timing, the + * resolution is specified in ticks per frame. * * @return the number of ticks per beat (PPQ) or per frame (SMPTE) * @see #getDivisionType @@ -233,9 +221,9 @@ return resolution; } - /** * Obtains the length of the MIDI file, expressed in 8-bit bytes. + * * @return the number of bytes in the file, or UNKNOWN_LENGTH if not known * @see #UNKNOWN_LENGTH */ @@ -245,7 +233,9 @@ /** * Obtains the length of the MIDI file, expressed in microseconds. - * @return the file's duration in microseconds, or UNKNOWN_LENGTH if not known + * + * @return the file's duration in microseconds, or UNKNOWN_LENGTH if not + * known * @see Sequence#getMicrosecondLength() * @see #getByteLength * @see #UNKNOWN_LENGTH @@ -255,14 +245,11 @@ } /** - * Obtain an unmodifiable map of properties. - * The concept of properties is further explained in - * the {@link MidiFileFormat class description}. + * Obtain an unmodifiable map of properties. The concept of properties is + * further explained in the {@link MidiFileFormat class description}. * - * @return a Map<String,Object> object containing - * all properties. If no properties are recognized, an empty map is - * returned. - * + * @return a {@code Map} object containing all properties. If + * no properties are recognized, an empty map is returned. * @see #getProperty(String) * @since 1.5 */ @@ -277,20 +264,16 @@ return Collections.unmodifiableMap(ret); } - /** - * Obtain the property value specified by the key. - * The concept of properties is further explained in - * the {@link MidiFileFormat class description}. + * Obtain the property value specified by the key. The concept of properties + * is further explained in the {@link MidiFileFormat class description}. + *

+ * If the specified property is not defined for a particular file format, + * this method returns {@code null}. * - *

If the specified property is not defined for a - * particular file format, this method returns - * null. - * - * @param key the key of the desired property - * @return the value of the property with the specified key, - * or null if the property does not exist. - * + * @param key the key of the desired property + * @return the value of the property with the specified key, or {@code null} + * if the property does not exist * @see #properties() * @since 1.5 */ @@ -300,6 +283,4 @@ } return properties.get(key); } - - } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/midi/MidiMessage.java --- a/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiMessage.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiMessage.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -26,83 +26,76 @@ package javax.sound.midi; /** - * MidiMessage is the base class for MIDI messages. They include - * not only the standard MIDI messages that a synthesizer can respond to, but also - * "meta-events" that can be used by sequencer programs. There are meta-events + * {@code MidiMessage} is the base class for MIDI messages. They include not + * only the standard MIDI messages that a synthesizer can respond to, but also + * "meta-events" that can be used by sequencer programs. There are meta-events * for such information as lyrics, copyrights, tempo indications, time and key - * signatures, markers, etc. For more information, see the Standard MIDI Files 1.0 - * specification, which is part of the Complete MIDI 1.0 Detailed Specification - * published by the MIDI Manufacturer's Association + * signatures, markers, etc. For more information, see the Standard MIDI Files + * 1.0 specification, which is part of the Complete MIDI 1.0 Detailed + * Specification published by the MIDI Manufacturer's Association * (http://www.midi.org). *

- * The base MidiMessage class provides access to three types of + * The base {@code MidiMessage} class provides access to three types of * information about a MIDI message: *

    *
  • The messages's status byte
    • - *
  • The total length of the message in bytes (the status byte plus any data bytes)
    • + *
  • The total length of the message in bytes (the status byte plus any data + * bytes)
    • *
  • A byte array containing the complete message
    • *
* - * MidiMessage includes methods to get, but not set, these values. + * {@code MidiMessage} includes methods to get, but not set, these values. * Setting them is a subclass responsibility. *

- * - * The MIDI standard expresses MIDI data in bytes. However, because - * JavaTM uses signed bytes, the Java Sound API uses integers - * instead of bytes when expressing MIDI data. For example, the - * {@link #getStatus()} method of - * MidiMessage returns MIDI status bytes as integers. If you are - * processing MIDI data that originated outside Java Sound and now - * is encoded as signed bytes, the bytes can - * can be converted to integers using this conversion: + * The MIDI standard expresses MIDI data in + * bytes. However, because JavaTM uses signed bytes, the Java Sound + * API uses integers instead of bytes when expressing MIDI data. For example, + * the {@link #getStatus()} method of {@code MidiMessage} returns MIDI status + * bytes as integers. If you are processing MIDI data that originated outside + * Java Sound and now is encoded as signed bytes, the bytes can can be + * converted to integers using this conversion: + * *

{@code int i = (int)(byte & 0xFF)}
*

- * If you simply need to pass a known MIDI byte value as a method parameter, - * it can be expressed directly as an integer, using (for example) decimal or - * hexadecimal notation. For instance, to pass the "active sensing" status byte + * If you simply need to pass a known MIDI byte value as a method parameter, it + * can be expressed directly as an integer, using (for example) decimal or + * hexadecimal notation. For instance, to pass the "active sensing" status byte * as the first argument to ShortMessage's - * {@link ShortMessage#setMessage(int) setMessage(int)} - * method, you can express it as 254 or 0xFE. + * {@link ShortMessage#setMessage(int) setMessage(int)} method, you can express + * it as 254 or 0xFE. * + * @author David Rivas + * @author Kara Kytle * @see Track * @see Sequence * @see Receiver - * - * @author David Rivas - * @author Kara Kytle */ - public abstract class MidiMessage implements Cloneable { - // Instance variables - /** - * The MIDI message data. The first byte is the status - * byte for the message; subsequent bytes up to the length - * of the message are data bytes for this message. + * The MIDI message data. The first byte is the status byte for the message; + * subsequent bytes up to the length of the message are data bytes for this + * message. + * * @see #getLength */ protected byte[] data; - /** - * The number of bytes in the MIDI message, including the - * status byte and any data bytes. + * The number of bytes in the MIDI message, including the status byte and + * any data bytes. + * * @see #getLength */ protected int length = 0; - /** - * Constructs a new MidiMessage. This protected - * constructor is called by concrete subclasses, which should - * ensure that the data array specifies a complete, valid MIDI - * message. + * Constructs a new {@code MidiMessage}. This protected constructor is + * called by concrete subclasses, which should ensure that the data array + * specifies a complete, valid MIDI message. * - * @param data an array of bytes containing the complete message. - * The message data may be changed using the setMessage - * method. - * + * @param data an array of bytes containing the complete message. The + * message data may be changed using the {@code setMessage} method. * @see #setMessage */ protected MidiMessage(byte[] data) { @@ -112,20 +105,21 @@ } } - /** - * Sets the data for the MIDI message. This protected - * method is called by concrete subclasses, which should - * ensure that the data array specifies a complete, valid MIDI - * message. + * Sets the data for the MIDI message. This protected method is called by + * concrete subclasses, which should ensure that the data array specifies a + * complete, valid MIDI message. * - * @param data the data bytes in the MIDI message - * @param length the number of bytes in the data byte array - * @throws InvalidMidiDataException if the parameter values do not specify a valid MIDI meta message + * @param data the data bytes in the MIDI message + * @param length the number of bytes in the data byte array + * @throws InvalidMidiDataException if the parameter values do not specify a + * valid MIDI meta message */ - protected void setMessage(byte[] data, int length) throws InvalidMidiDataException { + protected void setMessage(byte[] data, int length) + throws InvalidMidiDataException { if (length < 0 || (length > 0 && length > data.length)) { - throw new IndexOutOfBoundsException("length out of bounds: "+length); + throw new IndexOutOfBoundsException( + "length out of bounds: " + length); } this.length = length; @@ -135,16 +129,14 @@ System.arraycopy(data, 0, this.data, 0, length); } - /** - * Obtains the MIDI message data. The first byte of the returned byte - * array is the status byte of the message. Any subsequent bytes up to - * the length of the message are data bytes. The byte array may have a - * length which is greater than that of the actual message; the total - * length of the message in bytes is reported by the {@link #getLength} - * method. + * Obtains the MIDI message data. The first byte of the returned byte array + * is the status byte of the message. Any subsequent bytes up to the length + * of the message are data bytes. The byte array may have a length which is + * greater than that of the actual message; the total length of the message + * in bytes is reported by the {@link #getLength} method. * - * @return the byte array containing the complete MidiMessage data + * @return the byte array containing the complete {@code MidiMessage} data */ public byte[] getMessage() { byte[] returnedArray = new byte[length]; @@ -152,12 +144,11 @@ return returnedArray; } - /** - * Obtains the status byte for the MIDI message. The status "byte" is + * Obtains the status byte for the MIDI message. The status "byte" is * represented as an integer; see the - * discussion in the - * MidiMessage class description. + * discussion in the {@code MidiMessage} + * class description. * * @return the integer representation of this event's status byte */ @@ -168,13 +159,11 @@ return 0; } - /** - * Obtains the total length of the MIDI message in bytes. A - * MIDI message consists of one status byte and zero or more - * data bytes. The return value ranges from 1 for system real-time messages, - * to 2 or 3 for channel messages, to any value for meta and system - * exclusive messages. + * Obtains the total length of the MIDI message in bytes. A MIDI message + * consists of one status byte and zero or more data bytes. The return value + * ranges from 1 for system real-time messages, to 2 or 3 for channel + * messages, to any value for meta and system exclusive messages. * * @return the length of the message in bytes */ @@ -182,11 +171,11 @@ return length; } - /** - * Creates a new object of the same class and with the same contents - * as this object. - * @return a clone of this instance. + * Creates a new object of the same class and with the same contents as this + * object. + * + * @return a clone of this instance */ public abstract Object clone(); } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/midi/MidiSystem.java --- a/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiSystem.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiSystem.java Tue Aug 19 10:32:16 2014 -0700 @@ -25,59 +25,52 @@ package javax.sound.midi; -import java.io.FileInputStream; import java.io.File; +import java.io.IOException; import java.io.InputStream; import java.io.OutputStream; -import java.io.IOException; - +import java.net.URL; import java.util.ArrayList; import java.util.HashSet; import java.util.Iterator; import java.util.List; +import java.util.Properties; import java.util.Set; -import java.net.URL; - +import javax.sound.midi.spi.MidiDeviceProvider; +import javax.sound.midi.spi.MidiFileReader; import javax.sound.midi.spi.MidiFileWriter; -import javax.sound.midi.spi.MidiFileReader; import javax.sound.midi.spi.SoundbankReader; -import javax.sound.midi.spi.MidiDeviceProvider; +import com.sun.media.sound.AutoConnectSequencer; import com.sun.media.sound.JDK13Services; -import com.sun.media.sound.ReferenceCountingDevice; -import com.sun.media.sound.AutoConnectSequencer; import com.sun.media.sound.MidiDeviceReceiverEnvelope; import com.sun.media.sound.MidiDeviceTransmitterEnvelope; - +import com.sun.media.sound.ReferenceCountingDevice; /** - * The MidiSystem class provides access to the installed MIDI - * system resources, including devices such as synthesizers, sequencers, and - * MIDI input and output ports. A typical simple MIDI application might - * begin by invoking one or more MidiSystem methods to learn - * what devices are installed and to obtain the ones needed in that - * application. + * The {@code MidiSystem} class provides access to the installed MIDI system + * resources, including devices such as synthesizers, sequencers, and MIDI input + * and output ports. A typical simple MIDI application might begin by invoking + * one or more {@code MidiSystem} methods to learn what devices are installed + * and to obtain the ones needed in that application. *

- * The class also has methods for reading files, streams, and URLs that - * contain standard MIDI file data or soundbanks. You can query the - * MidiSystem for the format of a specified MIDI file. + * The class also has methods for reading files, streams, and URLs that contain + * standard MIDI file data or soundbanks. You can query the {@code MidiSystem} + * for the format of a specified MIDI file. *

- * You cannot instantiate a MidiSystem; all the methods are - * static. - * - *

Properties can be used to specify default MIDI devices. - * Both system properties and a properties file are considered. - * The sound.properties properties file is read from - * an implementation-specific location (typically it is the lib - * directory in the Java installation directory). - * If a property exists both as a system property and in the - * properties file, the system property takes precedence. If none is - * specified, a suitable default is chosen among the available devices. - * The syntax of the properties file is specified in - * {@link java.util.Properties#load(InputStream) Properties.load}. The - * following table lists the available property keys and which methods - * consider them: + * You cannot instantiate a {@code MidiSystem}; all the methods are static. + *

+ * Properties can be used to specify default MIDI devices. Both system + * properties and a properties file are considered. The "sound.properties" + * properties file is read from an implementation-specific location (typically + * it is the {@code lib} directory in the Java installation directory). If a + * property exists both as a system property and in the properties file, the + * system property takes precedence. If none is specified, a suitable default is + * chosen among the available devices. The syntax of the properties file is + * specified in {@link Properties#load(InputStream) Properties.load}. The + * following table lists the available property keys and which methods consider + * them: * * * @@ -87,80 +80,64 @@ * * * - * + * * * * * - * + * * * * * - * + * * * * * - * + * * * * *
MIDI System Property Keys
Affected Method
javax.sound.midi.Receiver{@code javax.sound.midi.Receiver}{@link Receiver}{@link #getReceiver}
javax.sound.midi.Sequencer{@code javax.sound.midi.Sequencer}{@link Sequencer}{@link #getSequencer}
javax.sound.midi.Synthesizer{@code javax.sound.midi.Synthesizer}{@link Synthesizer}{@link #getSynthesizer}
javax.sound.midi.Transmitter{@code javax.sound.midi.Transmitter}{@link Transmitter}{@link #getTransmitter}
* - * The property value consists of the provider class name - * and the device name, separated by the hash mark ("#"). - * The provider class name is the fully-qualified - * name of a concrete {@link javax.sound.midi.spi.MidiDeviceProvider - * MIDI device provider} class. The device name is matched against - * the String returned by the getName - * method of MidiDevice.Info. - * Either the class name, or the device name may be omitted. - * If only the class name is specified, the trailing hash mark - * is optional. - * - *

If the provider class is specified, and it can be - * successfully retrieved from the installed providers, - * the list of - * MidiDevice.Info objects is retrieved - * from the provider. Otherwise, or when these devices - * do not provide a subsequent match, the list is retrieved - * from {@link #getMidiDeviceInfo} to contain - * all available MidiDevice.Info objects. - * - *

If a device name is specified, the resulting list of - * MidiDevice.Info objects is searched: - * the first one with a matching name, and whose - * MidiDevice implements the - * respective interface, will be returned. - * If no matching MidiDevice.Info object - * is found, or the device name is not specified, - * the first suitable device from the resulting - * list will be returned. For Sequencer and Synthesizer, - * a device is suitable if it implements the respective - * interface; whereas for Receiver and Transmitter, a device is - * suitable if it - * implements neither Sequencer nor Synthesizer and provides - * at least one Receiver or Transmitter, respectively. - * - * For example, the property javax.sound.midi.Receiver - * with a value - * "com.sun.media.sound.MidiProvider#SunMIDI1" - * will have the following consequences when - * getReceiver is called: - * if the class com.sun.media.sound.MidiProvider exists - * in the list of installed MIDI device providers, - * the first Receiver device with name - * "SunMIDI1" will be returned. If it cannot - * be found, the first Receiver from that provider - * will be returned, regardless of name. - * If there is none, the first Receiver with name - * "SunMIDI1" in the list of all devices - * (as returned by getMidiDeviceInfo) will be returned, - * or, if not found, the first Receiver that can - * be found in the list of all devices is returned. - * If that fails, too, a MidiUnavailableException - * is thrown. + * The property value consists of the provider class name and the device name, + * separated by the hash mark ("#"). The provider class name is the + * fully-qualified name of a concrete + * {@link MidiDeviceProvider MIDI device provider} class. The device name is + * matched against the {@code String} returned by the {@code getName} method of + * {@code MidiDevice.Info}. Either the class name, or the device name may be + * omitted. If only the class name is specified, the trailing hash mark is + * optional. + *

+ * If the provider class is specified, and it can be successfully retrieved from + * the installed providers, the list of {@code MidiDevice.Info} objects is + * retrieved from the provider. Otherwise, or when these devices do not provide + * a subsequent match, the list is retrieved from {@link #getMidiDeviceInfo} to + * contain all available {@code MidiDevice.Info} objects. + *

+ * If a device name is specified, the resulting list of {@code MidiDevice.Info} + * objects is searched: the first one with a matching name, and whose + * {@code MidiDevice} implements the respective interface, will be returned. If + * no matching {@code MidiDevice.Info} object is found, or the device name is + * not specified, the first suitable device from the resulting list will be + * returned. For Sequencer and Synthesizer, a device is suitable if it + * implements the respective interface; whereas for Receiver and Transmitter, a + * device is suitable if it implements neither Sequencer nor Synthesizer and + * provides at least one Receiver or Transmitter, respectively. + *

+ * For example, the property {@code javax.sound.midi.Receiver} with a value + * {@code "com.sun.media.sound.MidiProvider#SunMIDI1"} will have the following + * consequences when {@code getReceiver} is called: if the class + * {@code com.sun.media.sound.MidiProvider} exists in the list of installed MIDI + * device providers, the first {@code Receiver} device with name + * {@code "SunMIDI1"} will be returned. If it cannot be found, the first + * {@code Receiver} from that provider will be returned, regardless of name. If + * there is none, the first {@code Receiver} with name {@code "SunMIDI1"} in the + * list of all devices (as returned by {@code getMidiDeviceInfo}) will be + * returned, or, if not found, the first {@code Receiver} that can be found in + * the list of all devices is returned. If that fails, too, a + * {@code MidiUnavailableException} is thrown. * * @author Kara Kytle * @author Florian Bomers @@ -174,17 +151,15 @@ private MidiSystem() { } - /** - * Obtains an array of information objects representing - * the set of all MIDI devices available on the system. - * A returned information object can then be used to obtain the - * corresponding device object, by invoking + * Obtains an array of information objects representing the set of all MIDI + * devices available on the system. A returned information object can then + * be used to obtain the corresponding device object, by invoking * {@link #getMidiDevice(MidiDevice.Info) getMidiDevice}. * - * @return an array of MidiDevice.Info objects, one - * for each installed MIDI device. If no such devices are installed, - * an array of length 0 is returned. + * @return an array of {@code MidiDevice.Info} objects, one for each + * installed MIDI device. If no such devices are installed, an array + * of length 0 is returned. */ public static MidiDevice.Info[] getMidiDeviceInfo() { List allInfos = new ArrayList<>(); @@ -201,16 +176,15 @@ return infosArray; } - /** * Obtains the requested MIDI device. * - * @param info a device information object representing the desired device. + * @param info a device information object representing the desired device * @return the requested device * @throws MidiUnavailableException if the requested device is not available - * due to resource restrictions - * @throws IllegalArgumentException if the info object does not represent - * a MIDI device installed on the system + * due to resource restrictions + * @throws IllegalArgumentException if the info object does not represent a + * MIDI device installed on the system * @see #getMidiDeviceInfo */ public static MidiDevice getMidiDevice(MidiDevice.Info info) throws MidiUnavailableException { @@ -226,44 +200,38 @@ throw new IllegalArgumentException("Requested device not installed: " + info); } - /** - * Obtains a MIDI receiver from an external MIDI port - * or other default device. - * The returned receiver always implements - * the {@code MidiDeviceReceiver} interface. - * - *

If the system property - * javax.sound.midi.Receiver - * is defined or it is defined in the file "sound.properties", - * it is used to identify the device that provides the default receiver. - * For details, refer to the {@link MidiSystem class description}. - * - * If a suitable MIDI port is not available, the Receiver is - * retrieved from an installed synthesizer. - * - *

If a native receiver provided by the default device does not implement - * the {@code MidiDeviceReceiver} interface, it will be wrapped in a - * wrapper class that implements the {@code MidiDeviceReceiver} interface. - * The corresponding {@code Receiver} method calls will be forwarded - * to the native receiver. - * - *

If this method returns successfully, the {@link - * javax.sound.midi.MidiDevice MidiDevice} the - * Receiver belongs to is opened implicitly, if it is - * not already open. It is possible to close an implicitly opened - * device by calling {@link javax.sound.midi.Receiver#close close} - * on the returned Receiver. All open Receiver - * instances have to be closed in order to release system resources - * hold by the MidiDevice. For a - * detailed description of open/close behaviour see the class - * description of {@link javax.sound.midi.MidiDevice MidiDevice}. - * + * Obtains a MIDI receiver from an external MIDI port or other default + * device. The returned receiver always implements the + * {@code MidiDeviceReceiver} interface. + *

+ * If the system property {@code javax.sound.midi.Receiver} is defined or it + * is defined in the file "sound.properties", it is used to identify the + * device that provides the default receiver. For details, refer to the + * {@link MidiSystem class description}. + *

+ * If a suitable MIDI port is not available, the Receiver is retrieved from + * an installed synthesizer. + *

+ * If a native receiver provided by the default device does not implement + * the {@code MidiDeviceReceiver} interface, it will be wrapped in a wrapper + * class that implements the {@code MidiDeviceReceiver} interface. The + * corresponding {@code Receiver} method calls will be forwarded to the + * native receiver. + *

+ * If this method returns successfully, the {@link MidiDevice MidiDevice} + * the {@code Receiver} belongs to is opened implicitly, if it is not + * already open. It is possible to close an implicitly opened device by + * calling {@link Receiver#close close} on the returned {@code Receiver}. + * All open {@code Receiver} instances have to be closed in order to release + * system resources hold by the {@code MidiDevice}. For a detailed + * description of open/close behaviour see the class description of + * {@link MidiDevice MidiDevice}. * * @return the default MIDI receiver - * @throws MidiUnavailableException if the default receiver is not - * available due to resource restrictions, - * or no device providing receivers is installed in the system + * @throws MidiUnavailableException if the default receiver is not available + * due to resource restrictions, or no device providing receivers is + * installed in the system */ public static Receiver getReceiver() throws MidiUnavailableException { // may throw MidiUnavailableException @@ -280,41 +248,35 @@ return receiver; } - /** - * Obtains a MIDI transmitter from an external MIDI port - * or other default source. - * The returned transmitter always implements - * the {@code MidiDeviceTransmitter} interface. - * - *

If the system property - * javax.sound.midi.Transmitter - * is defined or it is defined in the file "sound.properties", - * it is used to identify the device that provides the default transmitter. - * For details, refer to the {@link MidiSystem class description}. - * - *

If a native transmitter provided by the default device does not implement + * Obtains a MIDI transmitter from an external MIDI port or other default + * source. The returned transmitter always implements the + * {@code MidiDeviceTransmitter} interface. + *

+ * If the system property {@code javax.sound.midi.Transmitter} is defined or + * it is defined in the file "sound.properties", it is used to identify the + * device that provides the default transmitter. For details, refer to the + * {@link MidiSystem class description}. + *

+ * If a native transmitter provided by the default device does not implement * the {@code MidiDeviceTransmitter} interface, it will be wrapped in a - * wrapper class that implements the {@code MidiDeviceTransmitter} interface. - * The corresponding {@code Transmitter} method calls will be forwarded - * to the native transmitter. - * - *

If this method returns successfully, the {@link - * javax.sound.midi.MidiDevice MidiDevice} the - * Transmitter belongs to is opened implicitly, if it - * is not already open. It is possible to close an implicitly - * opened device by calling {@link - * javax.sound.midi.Transmitter#close close} on the returned - * Transmitter. All open Transmitter - * instances have to be closed in order to release system resources - * hold by the MidiDevice. For a detailed description - * of open/close behaviour see the class description of {@link - * javax.sound.midi.MidiDevice MidiDevice}. + * wrapper class that implements the {@code MidiDeviceTransmitter} + * interface. The corresponding {@code Transmitter} method calls will be + * forwarded to the native transmitter. + *

+ * If this method returns successfully, the {@link MidiDevice MidiDevice} + * the {@code Transmitter} belongs to is opened implicitly, if it is not + * already open. It is possible to close an implicitly opened device by + * calling {@link Transmitter#close close} on the returned + * {@code Transmitter}. All open {@code Transmitter} instances have to be + * closed in order to release system resources hold by the + * {@code MidiDevice}. For a detailed description of open/close behaviour + * see the class description of {@link MidiDevice MidiDevice}. * * @return the default MIDI transmitter * @throws MidiUnavailableException if the default transmitter is not - * available due to resource restrictions, - * or no device providing transmitters is installed in the system + * available due to resource restrictions, or no device providing + * transmitters is installed in the system */ public static Transmitter getTransmitter() throws MidiUnavailableException { // may throw MidiUnavailableException @@ -331,59 +293,48 @@ return transmitter; } - /** * Obtains the default synthesizer. - * - *

If the system property - * javax.sound.midi.Synthesizer - * is defined or it is defined in the file "sound.properties", - * it is used to identify the default synthesizer. - * For details, refer to the {@link MidiSystem class description}. + *

+ * If the system property {@code javax.sound.midi.Synthesizer} is defined or + * it is defined in the file "sound.properties", it is used to identify the + * default synthesizer. For details, refer to the + * {@link MidiSystem class description}. * * @return the default synthesizer - * @throws MidiUnavailableException if the synthesizer is not - * available due to resource restrictions, - * or no synthesizer is installed in the system + * @throws MidiUnavailableException if the synthesizer is not available due + * to resource restrictions, or no synthesizer is installed in the + * system */ public static Synthesizer getSynthesizer() throws MidiUnavailableException { // may throw MidiUnavailableException return (Synthesizer) getDefaultDeviceWrapper(Synthesizer.class); } - /** - * Obtains the default Sequencer, connected to - * a default device. - * The returned Sequencer instance is - * connected to the default Synthesizer, - * as returned by {@link #getSynthesizer}. - * If there is no Synthesizer - * available, or the default Synthesizer - * cannot be opened, the sequencer is connected - * to the default Receiver, as returned - * by {@link #getReceiver}. - * The connection is made by retrieving a Transmitter - * instance from the Sequencer and setting its - * Receiver. - * Closing and re-opening the sequencer will restore the - * connection to the default device. - * - *

This method is equivalent to calling - * getSequencer(true). - * - *

If the system property - * javax.sound.midi.Sequencer - * is defined or it is defined in the file "sound.properties", - * it is used to identify the default sequencer. - * For details, refer to the {@link MidiSystem class description}. + * Obtains the default {@code Sequencer}, connected to a default device. The + * returned {@code Sequencer} instance is connected to the default + * {@code Synthesizer}, as returned by {@link #getSynthesizer}. If there is + * no {@code Synthesizer} available, or the default {@code Synthesizer} + * cannot be opened, the {@code sequencer} is connected to the default + * {@code Receiver}, as returned by {@link #getReceiver}. The connection is + * made by retrieving a {@code Transmitter} instance from the + * {@code Sequencer} and setting its {@code Receiver}. Closing and + * re-opening the sequencer will restore the connection to the default + * device. + *

+ * This method is equivalent to calling {@code getSequencer(true)}. + *

+ * If the system property {@code javax.sound.midi.Sequencer} is defined or + * it is defined in the file "sound.properties", it is used to identify the + * default sequencer. For details, refer to the + * {@link MidiSystem class description}. * * @return the default sequencer, connected to a default Receiver - * @throws MidiUnavailableException if the sequencer is not - * available due to resource restrictions, - * or there is no Receiver available by any - * installed MidiDevice, - * or no sequencer is installed in the system. + * @throws MidiUnavailableException if the sequencer is not available due to + * resource restrictions, or there is no {@code Receiver} available + * by any installed {@code MidiDevice}, or no sequencer is installed + * in the system * @see #getSequencer(boolean) * @see #getSynthesizer * @see #getReceiver @@ -392,49 +343,37 @@ return getSequencer(true); } - - /** - * Obtains the default Sequencer, optionally - * connected to a default device. - * - *

If connected is true, the returned - * Sequencer instance is - * connected to the default Synthesizer, - * as returned by {@link #getSynthesizer}. - * If there is no Synthesizer - * available, or the default Synthesizer - * cannot be opened, the sequencer is connected - * to the default Receiver, as returned - * by {@link #getReceiver}. - * The connection is made by retrieving a Transmitter - * instance from the Sequencer and setting its - * Receiver. - * Closing and re-opening the sequencer will restore the + * Obtains the default {@code Sequencer}, optionally connected to a default + * device. + *

+ * If {@code connected} is true, the returned {@code Sequencer} instance is + * connected to the default {@code Synthesizer}, as returned by + * {@link #getSynthesizer}. If there is no {@code Synthesizer} available, or + * the default {@code Synthesizer} cannot be opened, the {@code sequencer} + * is connected to the default {@code Receiver}, as returned by + * {@link #getReceiver}. The connection is made by retrieving a + * {@code Transmitter} instance from the {@code Sequencer} and setting its + * {@code Receiver}. Closing and re-opening the sequencer will restore the * connection to the default device. + *

+ * If {@code connected} is false, the returned {@code Sequencer} instance is + * not connected, it has no open {@code Transmitters}. In order to play the + * sequencer on a MIDI device, or a {@code Synthesizer}, it is necessary to + * get a {@code Transmitter} and set its {@code Receiver}. + *

+ * If the system property {@code javax.sound.midi.Sequencer} is defined or + * it is defined in the file "sound.properties", it is used to identify the + * default sequencer. For details, refer to the + * {@link MidiSystem class description}. * - *

If connected is false, the returned - * Sequencer instance is not connected, it - * has no open Transmitters. In order to - * play the sequencer on a MIDI device, or a Synthesizer, - * it is necessary to get a Transmitter and set its - * Receiver. - * - *

If the system property - * javax.sound.midi.Sequencer - * is defined or it is defined in the file "sound.properties", - * it is used to identify the default sequencer. - * For details, refer to the {@link MidiSystem class description}. - * - * @param connected whether or not the returned {@code Sequencer} - * is connected to the default {@code Synthesizer} + * @param connected whether or not the returned {@code Sequencer} is + * connected to the default {@code Synthesizer} * @return the default sequencer - * @throws MidiUnavailableException if the sequencer is not - * available due to resource restrictions, - * or no sequencer is installed in the system, - * or if connected is true, and there is - * no Receiver available by any installed - * MidiDevice + * @throws MidiUnavailableException if the sequencer is not available due to + * resource restrictions, or no sequencer is installed in the + * system, or if {@code connected} is true, and there is no + * {@code Receiver} available by any installed {@code MidiDevice} * @see #getSynthesizer * @see #getReceiver * @since 1.5 @@ -501,23 +440,20 @@ return seq; } - - - /** - * Constructs a MIDI sound bank by reading it from the specified stream. - * The stream must point to - * a valid MIDI soundbank file. In general, MIDI soundbank providers may - * need to read some data from the stream before determining whether they - * support it. These parsers must - * be able to mark the stream, read enough data to determine whether they - * support the stream, and, if not, reset the stream's read pointer to - * its original position. If the input stream does not support this, - * this method may fail with an IOException. - * @param stream the source of the sound bank data. + * Constructs a MIDI sound bank by reading it from the specified stream. The + * stream must point to a valid MIDI soundbank file. In general, MIDI + * soundbank providers may need to read some data from the stream before + * determining whether they support it. These parsers must be able to mark + * the stream, read enough data to determine whether they support the + * stream, and, if not, reset the stream's read pointer to its original + * position. If the input stream does not support this, this method may fail + * with an {@code IOException}. + * + * @param stream the source of the sound bank data * @return the sound bank - * @throws InvalidMidiDataException if the stream does not point to - * valid MIDI soundbank data recognized by the system + * @throws InvalidMidiDataException if the stream does not point to valid + * MIDI soundbank data recognized by the system * @throws IOException if an I/O error occurred when loading the soundbank * @see InputStream#markSupported * @see InputStream#mark @@ -542,15 +478,14 @@ } - /** - * Constructs a Soundbank by reading it from the specified URL. - * The URL must point to a valid MIDI soundbank file. + * Constructs a {@code Soundbank} by reading it from the specified URL. The + * URL must point to a valid MIDI soundbank file. * - * @param url the source of the sound bank data + * @param url the source of the sound bank data * @return the sound bank * @throws InvalidMidiDataException if the URL does not point to valid MIDI - * soundbank data recognized by the system + * soundbank data recognized by the system * @throws IOException if an I/O error occurred when loading the soundbank */ public static Soundbank getSoundbank(URL url) @@ -573,16 +508,14 @@ } - /** - * Constructs a Soundbank by reading it from the specified - * File. - * The File must point to a valid MIDI soundbank file. + * Constructs a {@code Soundbank} by reading it from the specified + * {@code File}. The {@code File} must point to a valid MIDI soundbank file. * - * @param file the source of the sound bank data + * @param file the source of the sound bank data * @return the sound bank - * @throws InvalidMidiDataException if the File does not - * point to valid MIDI soundbank data recognized by the system + * @throws InvalidMidiDataException if the {@code File} does not point to + * valid MIDI soundbank data recognized by the system * @throws IOException if an I/O error occurred when loading the soundbank */ public static Soundbank getSoundbank(File file) @@ -604,35 +537,33 @@ throw new InvalidMidiDataException("cannot get soundbank from stream"); } - - /** * Obtains the MIDI file format of the data in the specified input stream. * The stream must point to valid MIDI file data for a file type recognized * by the system. *

* This method and/or the code it invokes may need to read some data from - * the stream to determine whether its data format is supported. The - * implementation may therefore - * need to mark the stream, read enough data to determine whether it is in - * a supported format, and reset the stream's read pointer to its original - * position. If the input stream does not permit this set of operations, - * this method may fail with an IOException. + * the stream to determine whether its data format is supported. The + * implementation may therefore need to mark the stream, read enough data to + * determine whether it is in a supported format, and reset the stream's + * read pointer to its original position. If the input stream does not + * permit this set of operations, this method may fail with an + * {@code IOException}. *

* This operation can only succeed for files of a type which can be parsed - * by an installed file reader. It may fail with an InvalidMidiDataException - * even for valid files if no compatible file reader is installed. It - * will also fail with an InvalidMidiDataException if a compatible file reader - * is installed, but encounters errors while determining the file format. + * by an installed file reader. It may fail with an + * {@code InvalidMidiDataException} even for valid files if no compatible + * file reader is installed. It will also fail with an + * {@code InvalidMidiDataException} if a compatible file reader is + * installed, but encounters errors while determining the file format. * - * @param stream the input stream from which file format information - * should be extracted - * @return an MidiFileFormat object describing the MIDI file - * format + * @param stream the input stream from which file format information should + * be extracted + * @return an {@code MidiFileFormat} object describing the MIDI file format * @throws InvalidMidiDataException if the stream does not point to valid - * MIDI file data recognized by the system + * MIDI file data recognized by the system * @throws IOException if an I/O exception occurs while accessing the - * stream + * stream * @see #getMidiFileFormat(URL) * @see #getMidiFileFormat(File) * @see InputStream#markSupported @@ -661,26 +592,24 @@ } } - /** - * Obtains the MIDI file format of the data in the specified URL. The URL - * must point to valid MIDI file data for a file type recognized - * by the system. + * Obtains the MIDI file format of the data in the specified URL. The URL + * must point to valid MIDI file data for a file type recognized by the + * system. *

* This operation can only succeed for files of a type which can be parsed - * by an installed file reader. It may fail with an InvalidMidiDataException - * even for valid files if no compatible file reader is installed. It - * will also fail with an InvalidMidiDataException if a compatible file reader - * is installed, but encounters errors while determining the file format. + * by an installed file reader. It may fail with an + * {@code InvalidMidiDataException} even for valid files if no compatible + * file reader is installed. It will also fail with an + * {@code InvalidMidiDataException} if a compatible file reader is + * installed, but encounters errors while determining the file format. * - * @param url the URL from which file format information should be - * extracted - * @return a MidiFileFormat object describing the MIDI file - * format + * @param url the URL from which file format information should be + * extracted + * @return a {@code MidiFileFormat} object describing the MIDI file format * @throws InvalidMidiDataException if the URL does not point to valid MIDI - * file data recognized by the system + * file data recognized by the system * @throws IOException if an I/O exception occurs while accessing the URL - * * @see #getMidiFileFormat(InputStream) * @see #getMidiFileFormat(File) */ @@ -707,26 +636,24 @@ } } - /** - * Obtains the MIDI file format of the specified File. The - * File must point to valid MIDI file data for a file type + * Obtains the MIDI file format of the specified {@code File}. The + * {@code File} must point to valid MIDI file data for a file type * recognized by the system. *

* This operation can only succeed for files of a type which can be parsed - * by an installed file reader. It may fail with an InvalidMidiDataException - * even for valid files if no compatible file reader is installed. It - * will also fail with an InvalidMidiDataException if a compatible file reader - * is installed, but encounters errors while determining the file format. + * by an installed file reader. It may fail with an + * {@code InvalidMidiDataException} even for valid files if no compatible + * file reader is installed. It will also fail with an + * {@code InvalidMidiDataException} if a compatible file reader is + * installed, but encounters errors while determining the file format. * - * @param file the File from which file format information - * should be extracted - * @return a MidiFileFormat object describing the MIDI file - * format - * @throws InvalidMidiDataException if the File does not point - * to valid MIDI file data recognized by the system + * @param file the {@code File} from which file format information should + * be extracted + * @return a {@code MidiFileFormat} object describing the MIDI file format + * @throws InvalidMidiDataException if the {@code File} does not point to + * valid MIDI file data recognized by the system * @throws IOException if an I/O exception occurs while accessing the file - * * @see #getMidiFileFormat(InputStream) * @see #getMidiFileFormat(URL) */ @@ -753,35 +680,33 @@ } } - /** - * Obtains a MIDI sequence from the specified input stream. The stream must - * point to valid MIDI file data for a file type recognized - * by the system. + * Obtains a MIDI sequence from the specified input stream. The stream must + * point to valid MIDI file data for a file type recognized by the system. *

- * This method and/or the code it invokes may need to read some data - * from the stream to determine whether - * its data format is supported. The implementation may therefore - * need to mark the stream, read enough data to determine whether it is in - * a supported format, and reset the stream's read pointer to its original - * position. If the input stream does not permit this set of operations, - * this method may fail with an IOException. + * This method and/or the code it invokes may need to read some data from + * the stream to determine whether its data format is supported. The + * implementation may therefore need to mark the stream, read enough data to + * determine whether it is in a supported format, and reset the stream's + * read pointer to its original position. If the input stream does not + * permit this set of operations, this method may fail with an + * {@code IOException}. *

* This operation can only succeed for files of a type which can be parsed - * by an installed file reader. It may fail with an InvalidMidiDataException - * even for valid files if no compatible file reader is installed. It - * will also fail with an InvalidMidiDataException if a compatible file reader - * is installed, but encounters errors while constructing the Sequence + * by an installed file reader. It may fail with an + * {@code InvalidMidiDataException} even for valid files if no compatible + * file reader is installed. It will also fail with an + * {@code InvalidMidiDataException} if a compatible file reader is + * installed, but encounters errors while constructing the {@code Sequence} * object from the file data. * - * @param stream the input stream from which the Sequence - * should be constructed - * @return a Sequence object based on the MIDI file data - * contained in the input stream - * @throws InvalidMidiDataException if the stream does not point to - * valid MIDI file data recognized by the system - * @throws IOException if an I/O exception occurs while accessing the - * stream + * @param stream the input stream from which the {@code Sequence} should be + * constructed + * @return a {@code Sequence} object based on the MIDI file data contained + * in the input stream + * @throws InvalidMidiDataException if the stream does not point to valid + * MIDI file data recognized by the system + * @throws IOException if an I/O exception occurs while accessing the stream * @see InputStream#markSupported * @see InputStream#mark */ @@ -808,25 +733,23 @@ } } - /** - * Obtains a MIDI sequence from the specified URL. The URL must - * point to valid MIDI file data for a file type recognized - * by the system. + * Obtains a MIDI sequence from the specified URL. The URL must point to + * valid MIDI file data for a file type recognized by the system. *

* This operation can only succeed for files of a type which can be parsed - * by an installed file reader. It may fail with an InvalidMidiDataException - * even for valid files if no compatible file reader is installed. It - * will also fail with an InvalidMidiDataException if a compatible file reader - * is installed, but encounters errors while constructing the Sequence + * by an installed file reader. It may fail with an + * {@code InvalidMidiDataException} even for valid files if no compatible + * file reader is installed. It will also fail with an + * {@code InvalidMidiDataException} if a compatible file reader is + * installed, but encounters errors while constructing the {@code Sequence} * object from the file data. * - * @param url the URL from which the Sequence should be - * constructed - * @return a Sequence object based on the MIDI file data - * pointed to by the URL + * @param url the URL from which the {@code Sequence} should be constructed + * @return a {@code Sequence} object based on the MIDI file data pointed to + * by the URL * @throws InvalidMidiDataException if the URL does not point to valid MIDI - * file data recognized by the system + * file data recognized by the system * @throws IOException if an I/O exception occurs while accessing the URL */ public static Sequence getSequence(URL url) @@ -852,25 +775,25 @@ } } - /** - * Obtains a MIDI sequence from the specified File. - * The File must point to valid MIDI file data - * for a file type recognized by the system. + * Obtains a MIDI sequence from the specified {@code File}. The {@code File} + * must point to valid MIDI file data for a file type recognized by the + * system. *

* This operation can only succeed for files of a type which can be parsed - * by an installed file reader. It may fail with an InvalidMidiDataException - * even for valid files if no compatible file reader is installed. It - * will also fail with an InvalidMidiDataException if a compatible file reader - * is installed, but encounters errors while constructing the Sequence + * by an installed file reader. It may fail with an + * {@code InvalidMidiDataException} even for valid files if no compatible + * file reader is installed. It will also fail with an + * {@code InvalidMidiDataException} if a compatible file reader is + * installed, but encounters errors while constructing the {@code Sequence} * object from the file data. * - * @param file the File from which the Sequence - * should be constructed - * @return a Sequence object based on the MIDI file data - * pointed to by the File + * @param file the {@code File} from which the {@code Sequence} should be + * constructed + * @return a {@code Sequence} object based on the MIDI file data pointed to + * by the File * @throws InvalidMidiDataException if the File does not point to valid MIDI - * file data recognized by the system + * file data recognized by the system * @throws IOException if an I/O exception occurs */ public static Sequence getSequence(File file) @@ -896,12 +819,12 @@ } } - /** * Obtains the set of MIDI file types for which file writing support is * provided by the system. - * @return array of unique file types. If no file types are supported, - * an array of length 0 is returned. + * + * @return array of unique file types. If no file types are supported, an + * array of length 0 is returned. */ public static int[] getMidiFileTypes() { @@ -927,13 +850,13 @@ return resultTypes; } - /** * Indicates whether file writing support for the specified MIDI file type * is provided by the system. - * @param fileType the file type for which write capabilities are queried - * @return true if the file type is supported, - * otherwise false + * + * @param fileType the file type for which write capabilities are queried + * @return {@code true} if the file type is supported, otherwise + * {@code false} */ public static boolean isFileTypeSupported(int fileType) { @@ -948,14 +871,13 @@ return false; } - /** * Obtains the set of MIDI file types that the system can write from the * sequence specified. - * @param sequence the sequence for which MIDI file type support - * is queried - * @return the set of unique supported file types. If no file types are supported, - * returns an array of length 0. + * + * @param sequence the sequence for which MIDI file type support is queried + * @return the set of unique supported file types. If no file types are + * supported, returns an array of length 0. */ public static int[] getMidiFileTypes(Sequence sequence) { @@ -981,15 +903,14 @@ return resultTypes; } - /** * Indicates whether a MIDI file of the file type specified can be written * from the sequence indicated. - * @param fileType the file type for which write capabilities - * are queried - * @param sequence the sequence for which file writing support is queried - * @return true if the file type is supported for this - * sequence, otherwise false + * + * @param fileType the file type for which write capabilities are queried + * @param sequence the sequence for which file writing support is queried + * @return {@code true} if the file type is supported for this sequence, + * otherwise {@code false} */ public static boolean isFileTypeSupported(int fileType, Sequence sequence) { @@ -1004,19 +925,20 @@ return false; } - /** * Writes a stream of bytes representing a file of the MIDI file type * indicated to the output stream provided. - * @param in sequence containing MIDI data to be written to the file - * @param fileType the file type of the file to be written to the output stream - * @param out stream to which the file data should be written + * + * @param in sequence containing MIDI data to be written to the file + * @param fileType the file type of the file to be written to the output + * stream + * @param out stream to which the file data should be written * @return the number of bytes written to the output stream * @throws IOException if an I/O exception occurs * @throws IllegalArgumentException if the file format is not supported by - * the system + * the system * @see #isFileTypeSupported(int, Sequence) - * @see #getMidiFileTypes(Sequence) + * @see #getMidiFileTypes(Sequence) */ public static int write(Sequence in, int fileType, OutputStream out) throws IOException { @@ -1038,19 +960,19 @@ return bytesWritten; } - /** * Writes a stream of bytes representing a file of the MIDI file type * indicated to the external file provided. - * @param in sequence containing MIDI data to be written to the file - * @param type the file type of the file to be written to the output stream - * @param out external file to which the file data should be written + * + * @param in sequence containing MIDI data to be written to the file + * @param type the file type of the file to be written to the output stream + * @param out external file to which the file data should be written * @return the number of bytes written to the file * @throws IOException if an I/O exception occurs - * @throws IllegalArgumentException if the file type is not supported by - * the system + * @throws IllegalArgumentException if the file type is not supported by the + * system * @see #isFileTypeSupported(int, Sequence) - * @see #getMidiFileTypes(Sequence) + * @see #getMidiFileTypes(Sequence) */ public static int write(Sequence in, int type, File out) throws IOException { @@ -1072,8 +994,6 @@ return bytesWritten; } - - // HELPER METHODS @SuppressWarnings("unchecked") private static List getMidiDeviceProviders() { @@ -1095,19 +1015,16 @@ return (List) getProviders(MidiFileReader.class); } - - /** Attempts to locate and return a default MidiDevice of the specified - * type. - * + /** + * Attempts to locate and return a default MidiDevice of the specified type. * This method wraps {@link #getDefaultDevice}. It catches the - * IllegalArgumentException thrown by - * getDefaultDevice and instead throws a - * MidiUnavailableException, with the catched + * {@code IllegalArgumentException} thrown by {@code getDefaultDevice} and + * instead throws a {@code MidiUnavailableException}, with the catched * exception chained. * - * @param deviceClass The requested device type, one of Synthesizer.class, - * Sequencer.class, Receiver.class or Transmitter.class. - * @throws MidiUnavalableException on failure. + * @param deviceClass The requested device type, one of Synthesizer.class, + * Sequencer.class, Receiver.class or Transmitter.class + * @throws MidiUnavailableException on failure */ private static MidiDevice getDefaultDeviceWrapper(Class deviceClass) throws MidiUnavailableException{ @@ -1120,13 +1037,12 @@ } } - - /** Attempts to locate and return a default MidiDevice of the specified - * type. + /** + * Attempts to locate and return a default MidiDevice of the specified type. * - * @param deviceClass The requested device type, one of Synthesizer.class, - * Sequencer.class, Receiver.class or Transmitter.class. - * @throws IllegalArgumentException on failure. + * @param deviceClass The requested device type, one of Synthesizer.class, + * Sequencer.class, Receiver.class or Transmitter.class + * @throws IllegalArgumentException on failure */ private static MidiDevice getDefaultDevice(Class deviceClass) { List providers = getMidiDeviceProviders(); @@ -1169,16 +1085,15 @@ throw new IllegalArgumentException("Requested device not installed"); } - - - /** Return a MidiDeviceProcider of a given class from the list of - MidiDeviceProviders. - - @param providerClassName The class name of the provider to be returned. - @param provider The list of MidiDeviceProviders that is searched. - @return A MidiDeviceProvider of the requested class, or null if none - is found. - */ + /** + * Return a MidiDeviceProvider of a given class from the list of + * MidiDeviceProviders. + * + * @param providerClassName The class name of the provider to be returned + * @param providers The list of MidiDeviceProviders that is searched + * @return A MidiDeviceProvider of the requested class, or null if none is + * found + */ private static MidiDeviceProvider getNamedProvider(String providerClassName, List providers) { for(int i = 0; i < providers.size(); i++) { @@ -1190,15 +1105,15 @@ return null; } - - /** Return a MidiDevice with a given name from a given MidiDeviceProvider. - @param deviceName The name of the MidiDevice to be returned. - @param provider The MidiDeviceProvider to check for MidiDevices. - @param deviceClass The requested device type, one of Synthesizer.class, - Sequencer.class, Receiver.class or Transmitter.class. - - @return A MidiDevice matching the requirements, or null if none is found. - */ + /** + * Return a MidiDevice with a given name from a given MidiDeviceProvider. + * + * @param deviceName The name of the MidiDevice to be returned + * @param provider The MidiDeviceProvider to check for MidiDevices + * @param deviceClass The requested device type, one of Synthesizer.class, + * Sequencer.class, Receiver.class or Transmitter.class + * @return A MidiDevice matching the requirements, or null if none is found + */ private static MidiDevice getNamedDevice(String deviceName, MidiDeviceProvider provider, Class deviceClass) { @@ -1222,14 +1137,14 @@ return null; } - - /** Return a MidiDevice with a given name from a given MidiDeviceProvider. - @param deviceName The name of the MidiDevice to be returned. - @param provider The MidiDeviceProvider to check for MidiDevices. - @param deviceClass The requested device type, one of Synthesizer.class, - Sequencer.class, Receiver.class or Transmitter.class. - - @return A MidiDevice matching the requirements, or null if none is found. + /** + * Return a MidiDevice with a given name from a given MidiDeviceProvider. + * + * @param deviceName The name of the MidiDevice to be returned + * @param provider The MidiDeviceProvider to check for MidiDevices + * @param deviceClass The requested device type, one of Synthesizer.class, + * Sequencer.class, Receiver.class or Transmitter.class + * @return A MidiDevice matching the requirements, or null if none is found */ private static MidiDevice getNamedDevice(String deviceName, MidiDeviceProvider provider, @@ -1249,16 +1164,16 @@ return null; } - - /** Return a MidiDevice with a given name from a list of - MidiDeviceProviders. - @param deviceName The name of the MidiDevice to be returned. - @param providers The List of MidiDeviceProviders to check for - MidiDevices. - @param deviceClass The requested device type, one of Synthesizer.class, - Sequencer.class, Receiver.class or Transmitter.class. - @return A Mixer matching the requirements, or null if none is found. - */ + /** + * Return a MidiDevice with a given name from a list of MidiDeviceProviders. + * + * @param deviceName The name of the MidiDevice to be returned + * @param providers The List of MidiDeviceProviders to check for + * MidiDevices + * @param deviceClass The requested device type, one of Synthesizer.class, + * Sequencer.class, Receiver.class or Transmitter.class + * @return A Mixer matching the requirements, or null if none is found + */ private static MidiDevice getNamedDevice(String deviceName, List providers, Class deviceClass) { @@ -1282,15 +1197,15 @@ return null; } - - /** Return a MidiDevice with a given name from a list of - MidiDeviceProviders. - @param deviceName The name of the MidiDevice to be returned. - @param providers The List of MidiDeviceProviders to check for - MidiDevices. - @param deviceClass The requested device type, one of Synthesizer.class, - Sequencer.class, Receiver.class or Transmitter.class. - @return A Mixer matching the requirements, or null if none is found. + /** + * Return a MidiDevice with a given name from a list of MidiDeviceProviders. + * + * @param deviceName The name of the MidiDevice to be returned + * @param providers The List of MidiDeviceProviders to check for + * MidiDevices + * @param deviceClass The requested device type, one of Synthesizer.class, + * Sequencer.class, Receiver.class or Transmitter.class + * @return A Mixer matching the requirements, or null if none is found */ private static MidiDevice getNamedDevice(String deviceName, List providers, @@ -1310,14 +1225,15 @@ return null; } - - /** From a given MidiDeviceProvider, return the first appropriate device. - @param provider The MidiDeviceProvider to check for MidiDevices. - @param deviceClass The requested device type, one of Synthesizer.class, - Sequencer.class, Receiver.class or Transmitter.class. - @return A MidiDevice is considered appropriate, or null if no - appropriate device is found. - */ + /** + * From a given MidiDeviceProvider, return the first appropriate device. + * + * @param provider The MidiDeviceProvider to check for MidiDevices + * @param deviceClass The requested device type, one of Synthesizer.class, + * Sequencer.class, Receiver.class or Transmitter.class + * @return A MidiDevice is considered appropriate, or null if no appropriate + * device is found + */ private static MidiDevice getFirstDevice(MidiDeviceProvider provider, Class deviceClass) { MidiDevice device; @@ -1340,13 +1256,14 @@ return null; } - - /** From a given MidiDeviceProvider, return the first appropriate device. - @param provider The MidiDeviceProvider to check for MidiDevices. - @param deviceClass The requested device type, one of Synthesizer.class, - Sequencer.class, Receiver.class or Transmitter.class. - @return A MidiDevice is considered appropriate, or null if no - appropriate device is found. + /** + * From a given MidiDeviceProvider, return the first appropriate device. + * + * @param provider The MidiDeviceProvider to check for MidiDevices + * @param deviceClass The requested device type, one of Synthesizer.class, + * Sequencer.class, Receiver.class or Transmitter.class + * @return A MidiDevice is considered appropriate, or null if no appropriate + * device is found */ private static MidiDevice getFirstDevice(MidiDeviceProvider provider, Class deviceClass, @@ -1363,15 +1280,16 @@ return null; } - - /** From a List of MidiDeviceProviders, return the first appropriate - MidiDevice. - @param providers The List of MidiDeviceProviders to search. - @param deviceClass The requested device type, one of Synthesizer.class, - Sequencer.class, Receiver.class or Transmitter.class. - @return A MidiDevice that is considered appropriate, or null - if none is found. - */ + /** + * From a List of MidiDeviceProviders, return the first appropriate + * MidiDevice. + * + * @param providers The List of MidiDeviceProviders to search + * @param deviceClass The requested device type, one of Synthesizer.class, + * Sequencer.class, Receiver.class or Transmitter.class + * @return A MidiDevice that is considered appropriate, or null if none is + * found + */ private static MidiDevice getFirstDevice(List providers, Class deviceClass) { MidiDevice device; @@ -1394,14 +1312,15 @@ return null; } - - /** From a List of MidiDeviceProviders, return the first appropriate - MidiDevice. - @param providers The List of MidiDeviceProviders to search. - @param deviceClass The requested device type, one of Synthesizer.class, - Sequencer.class, Receiver.class or Transmitter.class. - @return A MidiDevice that is considered appropriate, or null - if none is found. + /** + * From a List of MidiDeviceProviders, return the first appropriate + * MidiDevice. + * + * @param providers The List of MidiDeviceProviders to search + * @param deviceClass The requested device type, one of Synthesizer.class, + * Sequencer.class, Receiver.class or Transmitter.class + * @return A MidiDevice that is considered appropriate, or null if none is + * found */ private static MidiDevice getFirstDevice(List providers, Class deviceClass, @@ -1419,28 +1338,29 @@ return null; } - - /** Checks if a MidiDevice is appropriate. - If deviceClass is Synthesizer or Sequencer, a device implementing - the respective interface is considered appropriate. If deviceClass - is Receiver or Transmitter, a device is considered appropriate if - it implements neither Synthesizer nor Transmitter, and if it can - provide at least one Receiver or Transmitter, respectively. - - @param device the MidiDevice to test - @param allowSynthesizer if true, Synthesizers are considered - appropriate. Otherwise only pure MidiDevices are considered - appropriate (unless allowSequencer is true). This flag only has an - effect for deviceClass Receiver and Transmitter. For other device - classes (Sequencer and Synthesizer), this flag has no effect. - @param allowSequencer if true, Sequencers are considered - appropriate. Otherwise only pure MidiDevices are considered - appropriate (unless allowSynthesizer is true). This flag only has an - effect for deviceClass Receiver and Transmitter. For other device - classes (Sequencer and Synthesizer), this flag has no effect. - @return true if the device is considered appropriate according to the - rules given above, false otherwise. - */ + /** + * Checks if a MidiDevice is appropriate. If deviceClass is Synthesizer or + * Sequencer, a device implementing the respective interface is considered + * appropriate. If deviceClass is Receiver or Transmitter, a device is + * considered appropriate if it implements neither Synthesizer nor + * Transmitter, and if it can provide at least one Receiver or Transmitter, + * respectively. + * + * @param device the MidiDevice to test + * @param allowSynthesizer if true, Synthesizers are considered + * appropriate. Otherwise only pure MidiDevices are considered + * appropriate (unless allowSequencer is true). This flag only has + * an effect for deviceClass Receiver and Transmitter. For other + * device classes (Sequencer and Synthesizer), this flag has no + * effect. + * @param allowSequencer if true, Sequencers are considered appropriate. + * Otherwise only pure MidiDevices are considered appropriate + * (unless allowSynthesizer is true). This flag only has an effect + * for deviceClass Receiver and Transmitter. For other device + * classes (Sequencer and Synthesizer), this flag has no effect. + * @return true if the device is considered appropriate according to the + * rules given above, false otherwise + */ private static boolean isAppropriateDevice(MidiDevice device, Class deviceClass, boolean allowSynthesizer, @@ -1473,12 +1393,12 @@ return false; } - /** - * Obtains the set of services currently installed on the system - * using the SPI mechanism in 1.3. - * @return a List of instances of providers for the requested service. - * If no providers are available, a List of length 0 will be returned. + * Obtains the set of services currently installed on the system using the + * SPI mechanism in 1.3. + * + * @return a List of instances of providers for the requested service. If no + * providers are available, a List of length 0 will be returned. */ private static List getProviders(Class providerClass) { return JDK13Services.getProviders(providerClass); diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/midi/MidiUnavailableException.java --- a/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiUnavailableException.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiUnavailableException.java Tue Aug 19 10:32:16 2014 -0700 @@ -25,39 +25,37 @@ package javax.sound.midi; - /** - * A MidiUnavailableException is thrown when a requested MIDI - * component cannot be opened or created because it is unavailable. This often - * occurs when a device is in use by another application. More generally, it - * can occur when there is a finite number of a certain kind of resource that can - * be used for some purpose, and all of them are already in use (perhaps all by - * this application). For an example of the latter case, see the + * A {@code MidiUnavailableException} is thrown when a requested MIDI component + * cannot be opened or created because it is unavailable. This often occurs when + * a device is in use by another application. More generally, it can occur when + * there is a finite number of a certain kind of resource that can be used for + * some purpose, and all of them are already in use (perhaps all by this + * application). For an example of the latter case, see the * {@link Transmitter#setReceiver(Receiver) setReceiver} method of - * Transmitter. + * {@code Transmitter}. * * @author Kara Kytle */ public class MidiUnavailableException extends Exception { + private static final long serialVersionUID = 6093809578628944323L; /** - * Constructs a MidiUnavailableException that has - * null as its error detail message. + * Constructs a {@code MidiUnavailableException} that has {@code null} as + * its error detail message. */ public MidiUnavailableException() { - super(); } /** - * Constructs a MidiUnavailableException with the - * specified detail message. + * Constructs a {@code MidiUnavailableException} with the specified detail + * message. * - * @param message the string to display as an error detail message + * @param message the string to display as an error detail message */ - public MidiUnavailableException(String message) { - + public MidiUnavailableException(final String message) { super(message); } } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/midi/Patch.java --- a/jdk/src/java.desktop/share/classes/javax/sound/midi/Patch.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/Patch.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2002, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -25,88 +25,77 @@ package javax.sound.midi; - /** - * A Patch object represents a location, on a MIDI - * synthesizer, into which a single instrument is stored (loaded). - * Every Instrument object has its own Patch - * object that specifies the memory location - * into which that instrument should be loaded. The - * location is specified abstractly by a bank index and a program number (not by - * any scheme that directly refers to a specific address or offset in RAM). - * This is a hierarchical indexing scheme: MIDI provides for up to 16384 banks, - * each of which contains up to 128 program locations. For example, a - * minimal sort of synthesizer might have only one bank of instruments, and - * only 32 instruments (programs) in that bank. + * A {@code Patch} object represents a location, on a MIDI synthesizer, into + * which a single instrument is stored (loaded). Every {@code Instrument} object + * has its own {@code Patch} object that specifies the memory location into + * which that instrument should be loaded. The location is specified abstractly + * by a bank index and a program number (not by any scheme that directly refers + * to a specific address or offset in RAM). This is a hierarchical indexing + * scheme: MIDI provides for up to 16384 banks, each of which contains up to 128 + * program locations. For example, a minimal sort of synthesizer might have only + * one bank of instruments, and only 32 instruments (programs) in that bank. *

- * To select what instrument should play the notes on a particular MIDI - * channel, two kinds of MIDI message are used that specify a patch location: - * a bank-select command, and a program-change channel command. The Java Sound + * To select what instrument should play the notes on a particular MIDI channel, + * two kinds of MIDI message are used that specify a patch location: a + * bank-select command, and a program-change channel command. The Java Sound * equivalent is the - * {@link MidiChannel#programChange(int, int) programChange(int, int)} - * method of MidiChannel. + * {@link MidiChannel#programChange(int, int) programChange(int, int)} method of + * {@code MidiChannel}. * + * @author Kara Kytle * @see Instrument * @see Instrument#getPatch() * @see MidiChannel#programChange(int, int) * @see Synthesizer#loadInstruments(Soundbank, Patch[]) * @see Soundbank * @see Sequence#getPatchList() - * - * @author Kara Kytle */ - public class Patch { - /** - * Bank index + * Bank index. */ private final int bank; - /** - * Program change number + * Program change number. */ private final int program; - /** * Constructs a new patch object from the specified bank and program * numbers. - * @param bank the bank index (in the range from 0 to 16383) - * @param program the program index (in the range from 0 to 127) + * + * @param bank the bank index (in the range from 0 to 16383) + * @param program the program index (in the range from 0 to 127) */ public Patch(int bank, int program) { - this.bank = bank; this.program = program; } - /** - * Returns the number of the bank that contains the instrument - * whose location this Patch specifies. + * Returns the number of the bank that contains the instrument whose + * location this {@code Patch} specifies. + * * @return the bank number, whose range is from 0 to 16383 * @see MidiChannel#programChange(int, int) */ public int getBank() { - return bank; } - /** - * Returns the index, within - * a bank, of the instrument whose location this Patch specifies. + * Returns the index, within a bank, of the instrument whose location this + * {@code Patch} specifies. + * * @return the instrument's program number, whose range is from 0 to 127 - * * @see MidiChannel#getProgram * @see MidiChannel#programChange(int) * @see MidiChannel#programChange(int, int) */ public int getProgram() { - return program; } } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/midi/Receiver.java --- a/jdk/src/java.desktop/share/classes/javax/sound/midi/Receiver.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/Receiver.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2010, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -25,50 +25,46 @@ package javax.sound.midi; - /** - * A Receiver receives {@link MidiEvent} objects and - * typically does something useful in response, such as interpreting them to - * generate sound or raw MIDI output. Common MIDI receivers include - * synthesizers and MIDI Out ports. + * A {@code Receiver} receives {@link MidiEvent} objects and typically does + * something useful in response, such as interpreting them to generate sound or + * raw MIDI output. Common MIDI receivers include synthesizers and MIDI Out + * ports. * + * @author Kara Kytle * @see MidiDevice * @see Synthesizer * @see Transmitter - * - * @author Kara Kytle */ public interface Receiver extends AutoCloseable { + //$$fb 2002-04-12: fix for 4662090: Contradiction in Receiver specification - //$$fb 2002-04-12: fix for 4662090: Contradiction in Receiver specification /** - * Sends a MIDI message and time-stamp to this receiver. - * If time-stamping is not supported by this receiver, the time-stamp - * value should be -1. - * @param message the MIDI message to send - * @param timeStamp the time-stamp for the message, in microseconds. + * Sends a MIDI message and time-stamp to this receiver. If time-stamping is + * not supported by this receiver, the time-stamp value should be -1. + * + * @param message the MIDI message to send + * @param timeStamp the time-stamp for the message, in microseconds * @throws IllegalStateException if the receiver is closed */ - public void send(MidiMessage message, long timeStamp); + void send(MidiMessage message, long timeStamp); /** - * Indicates that the application has finished using the receiver, and - * that limited resources it requires may be released or made available. - * - *

If the creation of this Receiver resulted in - * implicitly opening the underlying device, the device is - * implicitly closed by this method. This is true unless the device is - * kept open by other Receiver or Transmitter - * instances that opened the device implicitly, and unless the device - * has been opened explicitly. If the device this - * Receiver is retrieved from is closed explicitly by - * calling {@link MidiDevice#close MidiDevice.close}, the - * Receiver is closed, too. For a detailed - * description of open/close behaviour see the class description - * of {@link javax.sound.midi.MidiDevice MidiDevice}. + * Indicates that the application has finished using the receiver, and that + * limited resources it requires may be released or made available. + *

+ * If the creation of this {@code Receiver} resulted in implicitly opening + * the underlying device, the device is implicitly closed by this method. + * This is true unless the device is kept open by other {@code Receiver} or + * {@code Transmitter} instances that opened the device implicitly, and + * unless the device has been opened explicitly. If the device this + * {@code Receiver} is retrieved from is closed explicitly by calling + * {@link MidiDevice#close MidiDevice.close}, the {@code Receiver} is + * closed, too. For a detailed description of open/close behaviour see the + * class description of {@link MidiDevice MidiDevice}. * * @see javax.sound.midi.MidiSystem#getReceiver */ - public void close(); + void close(); } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/midi/Sequence.java --- a/jdk/src/java.desktop/share/classes/javax/sound/midi/Sequence.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/Sequence.java Tue Aug 19 10:32:16 2014 -0700 @@ -26,72 +26,77 @@ package javax.sound.midi; import java.util.Vector; -import com.sun.media.sound.MidiUtils; - /** - * A Sequence is a data structure containing musical - * information (often an entire song or composition) that can be played - * back by a {@link Sequencer} object. Specifically, the - * Sequence contains timing - * information and one or more tracks. Each {@link Track track} consists of a - * series of MIDI events (such as note-ons, note-offs, program changes, and meta-events). - * The sequence's timing information specifies the type of unit that is used - * to time-stamp the events in the sequence. + * A {@code Sequence} is a data structure containing musical information (often + * an entire song or composition) that can be played back by a {@link Sequencer} + * object. Specifically, the {@code Sequence} contains timing information and + * one or more tracks. Each {@link Track track} consists of a series of MIDI + * events (such as note-ons, note-offs, program changes, and meta-events). The + * sequence's timing information specifies the type of unit that is used to + * time-stamp the events in the sequence. *

- * A Sequence can be created from a MIDI file by reading the file - * into an input stream and invoking one of the getSequence methods of - * {@link MidiSystem}. A sequence can also be built from scratch by adding new - * Tracks to an empty Sequence, and adding - * {@link MidiEvent} objects to these Tracks. + * A {@code Sequence} can be created from a MIDI file by reading the file into + * an input stream and invoking one of the {@code getSequence} methods of + * {@link MidiSystem}. A sequence can also be built from scratch by adding new + * {@code Tracks} to an empty {@code Sequence}, and adding {@link MidiEvent} + * objects to these {@code Tracks}. * + * @author Kara Kytle * @see Sequencer#setSequence(java.io.InputStream stream) * @see Sequencer#setSequence(Sequence sequence) * @see Track#add(MidiEvent) * @see MidiFileFormat - * - * @author Kara Kytle */ public class Sequence { - // Timing types /** - * The tempo-based timing type, for which the resolution is expressed in pulses (ticks) per quarter note. + * The tempo-based timing type, for which the resolution is expressed in + * pulses (ticks) per quarter note. + * * @see #Sequence(float, int) */ public static final float PPQ = 0.0f; /** - * The SMPTE-based timing type with 24 frames per second (resolution is expressed in ticks per frame). + * The SMPTE-based timing type with 24 frames per second (resolution is + * expressed in ticks per frame). + * * @see #Sequence(float, int) */ public static final float SMPTE_24 = 24.0f; /** - * The SMPTE-based timing type with 25 frames per second (resolution is expressed in ticks per frame). + * The SMPTE-based timing type with 25 frames per second (resolution is + * expressed in ticks per frame). + * * @see #Sequence(float, int) */ public static final float SMPTE_25 = 25.0f; /** - * The SMPTE-based timing type with 29.97 frames per second (resolution is expressed in ticks per frame). + * The SMPTE-based timing type with 29.97 frames per second (resolution is + * expressed in ticks per frame). + * * @see #Sequence(float, int) */ public static final float SMPTE_30DROP = 29.97f; /** - * The SMPTE-based timing type with 30 frames per second (resolution is expressed in ticks per frame). + * The SMPTE-based timing type with 30 frames per second (resolution is + * expressed in ticks per frame). + * * @see #Sequence(float, int) */ public static final float SMPTE_30 = 30.0f; - // Variables /** * The timing division type of the sequence. + * * @see #PPQ * @see #SMPTE_24 * @see #SMPTE_25 @@ -103,33 +108,33 @@ /** * The timing resolution of the sequence. + * * @see #getResolution */ protected int resolution; /** * The MIDI tracks in this sequence. + * * @see #getTracks */ protected Vector tracks = new Vector(); - /** - * Constructs a new MIDI sequence with the specified timing division - * type and timing resolution. The division type must be one of the - * recognized MIDI timing types. For tempo-based timing, - * divisionType is PPQ (pulses per quarter note) and - * the resolution is specified in ticks per beat. For SMTPE timing, - * divisionType specifies the number of frames per - * second and the resolution is specified in ticks per frame. - * The sequence will contain no initial tracks. Tracks may be - * added to or removed from the sequence using {@link #createTrack} - * and {@link #deleteTrack}. + * Constructs a new MIDI sequence with the specified timing division type + * and timing resolution. The division type must be one of the recognized + * MIDI timing types. For tempo-based timing, {@code divisionType} is PPQ + * (pulses per quarter note) and the resolution is specified in ticks per + * beat. For SMTPE timing, {@code divisionType} specifies the number of + * frames per second and the resolution is specified in ticks per frame. The + * sequence will contain no initial tracks. Tracks may be added to or + * removed from the sequence using {@link #createTrack} and + * {@link #deleteTrack}. * - * @param divisionType the timing division type (PPQ or one of the SMPTE types) - * @param resolution the timing resolution - * @throws InvalidMidiDataException if divisionType is not valid - * + * @param divisionType the timing division type (PPQ or one of the SMPTE + * types) + * @param resolution the timing resolution + * @throws InvalidMidiDataException if {@code divisionType} is not valid * @see #PPQ * @see #SMPTE_24 * @see #SMPTE_25 @@ -156,27 +161,25 @@ this.resolution = resolution; } - /** - * Constructs a new MIDI sequence with the specified timing division - * type, timing resolution, and number of tracks. The division type must be one of the - * recognized MIDI timing types. For tempo-based timing, - * divisionType is PPQ (pulses per quarter note) and - * the resolution is specified in ticks per beat. For SMTPE timing, - * divisionType specifies the number of frames per - * second and the resolution is specified in ticks per frame. - * The sequence will be initialized with the number of tracks specified by - * numTracks. These tracks are initially empty (i.e. - * they contain only the meta-event End of Track). - * The tracks may be retrieved for editing using the {@link #getTracks} - * method. Additional tracks may be added, or existing tracks removed, - * using {@link #createTrack} and {@link #deleteTrack}. + * Constructs a new MIDI sequence with the specified timing division type, + * timing resolution, and number of tracks. The division type must be one of + * the recognized MIDI timing types. For tempo-based timing, + * {@code divisionType} is PPQ (pulses per quarter note) and the resolution + * is specified in ticks per beat. For SMTPE timing, {@code divisionType} + * specifies the number of frames per second and the resolution is specified + * in ticks per frame. The sequence will be initialized with the number of + * tracks specified by {@code numTracks}. These tracks are initially empty + * (i.e. they contain only the meta-event End of Track). The tracks may be + * retrieved for editing using the {@link #getTracks} method. Additional + * tracks may be added, or existing tracks removed, using + * {@link #createTrack} and {@link #deleteTrack}. * - * @param divisionType the timing division type (PPQ or one of the SMPTE types) - * @param resolution the timing resolution - * @param numTracks the initial number of tracks in the sequence. - * @throws InvalidMidiDataException if divisionType is not valid - * + * @param divisionType the timing division type (PPQ or one of the SMPTE + * types) + * @param resolution the timing resolution + * @param numTracks the initial number of tracks in the sequence + * @throws InvalidMidiDataException if {@code divisionType} is not valid * @see #PPQ * @see #SMPTE_24 * @see #SMPTE_25 @@ -206,11 +209,10 @@ } } - /** * Obtains the timing division type for this sequence. + * * @return the division type (PPQ or one of the SMPTE types) - * * @see #PPQ * @see #SMPTE_24 * @see #SMPTE_25 @@ -223,11 +225,10 @@ return divisionType; } - /** - * Obtains the timing resolution for this sequence. - * If the sequence's division type is PPQ, the resolution is specified in ticks per beat. - * For SMTPE timing, the resolution is specified in ticks per frame. + * Obtains the timing resolution for this sequence. If the sequence's + * division type is PPQ, the resolution is specified in ticks per beat. For + * SMTPE timing, the resolution is specified in ticks per frame. * * @return the number of ticks per beat (PPQ) or per frame (SMPTE) * @see #getDivisionType @@ -238,13 +239,13 @@ return resolution; } - /** - * Creates a new, initially empty track as part of this sequence. - * The track initially contains the meta-event End of Track. - * The newly created track is returned. All tracks in the sequence - * may be retrieved using {@link #getTracks}. Tracks may be - * removed from the sequence using {@link #deleteTrack}. + * Creates a new, initially empty track as part of this sequence. The track + * initially contains the meta-event End of Track. The newly created track + * is returned. All tracks in the sequence may be retrieved using + * {@link #getTracks}. Tracks may be removed from the sequence using + * {@link #deleteTrack}. + * * @return the newly created track */ public Track createTrack() { @@ -255,13 +256,12 @@ return track; } - /** * Removes the specified track from the sequence. - * @param track the track to remove - * @return true if the track existed in the track and was removed, - * otherwise false. * + * @param track the track to remove + * @return {@code true} if the track existed in the track and was removed, + * otherwise {@code false} * @see #createTrack * @see #getTracks */ @@ -273,12 +273,11 @@ } } - /** - * Obtains an array containing all the tracks in this sequence. - * If the sequence contains no tracks, an array of length 0 is returned. + * Obtains an array containing all the tracks in this sequence. If the + * sequence contains no tracks, an array of length 0 is returned. + * * @return the array of tracks - * * @see #createTrack * @see #deleteTrack */ @@ -287,22 +286,20 @@ return tracks.toArray(new Track[tracks.size()]); } - /** * Obtains the duration of this sequence, expressed in microseconds. - * @return this sequence's duration in microseconds. + * + * @return this sequence's duration in microseconds */ public long getMicrosecondLength() { return com.sun.media.sound.MidiUtils.tick2microsecond(this, getTickLength(), null); } - /** * Obtains the duration of this sequence, expressed in MIDI ticks. * * @return this sequence's length in ticks - * * @see #getMicrosecondLength */ public long getTickLength() { @@ -321,15 +318,12 @@ } } - /** - * Obtains a list of patches referenced in this sequence. - * This patch list may be used to load the required - * {@link Instrument} objects - * into a {@link Synthesizer}. + * Obtains a list of patches referenced in this sequence. This patch list + * may be used to load the required {@link Instrument} objects into a + * {@link Synthesizer}. * - * @return an array of {@link Patch} objects used in this sequence - * + * @return an array of {@link Patch} objects used in this sequence * @see Synthesizer#loadInstruments(Soundbank, Patch[]) */ public Patch[] getPatchList() { diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/midi/Sequencer.java --- a/jdk/src/java.desktop/share/classes/javax/sound/midi/Sequencer.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/Sequencer.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -25,19 +25,18 @@ package javax.sound.midi; +import java.io.IOException; import java.io.InputStream; -import java.io.IOException; - /** * A hardware or software device that plays back a MIDI - * {@link Sequence sequence} is known as a sequencer. - * A MIDI sequence contains lists of time-stamped MIDI data, such as - * might be read from a standard MIDI file. Most - * sequencers also provide functions for creating and editing sequences. + * {@link Sequence sequence} is known as a sequencer. A MIDI sequence + * contains lists of time-stamped MIDI data, such as might be read from a + * standard MIDI file. Most sequencers also provide functions for creating and + * editing sequences. *

- * The Sequencer interface includes methods for the following - * basic MIDI sequencer operations: + * The {@code Sequencer} interface includes methods for the following basic MIDI + * sequencer operations: *

    *
  • obtaining a sequence from MIDI file data
    • *
  • starting and stopping playback
    • @@ -48,729 +47,635 @@ *
  • controlling the timing of another device
    • *
* In addition, the following operations are supported, either directly, or - * indirectly through objects that the Sequencer has access to: + * indirectly through objects that the {@code Sequencer} has access to: *
    *
  • editing the data by adding or deleting individual MIDI events or entire * tracks
    • *
  • muting or soloing individual tracks in the sequence
    • - *
  • notifying listener objects about any meta-events or - * control-change events encountered while playing back the sequence.
    • + *
  • notifying listener objects about any meta-events or control-change events + * encountered while playing back the sequence.
    • *
* - * @see Sequencer.SyncMode + * @author Kara Kytle + * @author Florian Bomers + * @see SyncMode * @see #addMetaEventListener * @see ControllerEventListener * @see Receiver * @see Transmitter * @see MidiDevice - * - * @author Kara Kytle - * @author Florian Bomers */ public interface Sequencer extends MidiDevice { - /** - * A value indicating that looping should continue - * indefinitely rather than complete after a specific - * number of loops. + * A value indicating that looping should continue indefinitely rather than + * complete after a specific number of loops. * * @see #setLoopCount * @since 1.5 */ - public static final int LOOP_CONTINUOUSLY = -1; - - - - /** - * Sets the current sequence on which the sequencer operates. - * - *

This method can be called even if the - * Sequencer is closed. - * - * @param sequence the sequence to be loaded. - * @throws InvalidMidiDataException if the sequence contains invalid - * MIDI data, or is not supported. - */ - public void setSequence(Sequence sequence) throws InvalidMidiDataException; - + int LOOP_CONTINUOUSLY = -1; /** * Sets the current sequence on which the sequencer operates. - * The stream must point to MIDI file data. - * - *

This method can be called even if the - * Sequencer is closed. + *

+ * This method can be called even if the {@code Sequencer} is closed. * - * @param stream stream containing MIDI file data. - * @throws IOException if an I/O exception occurs during reading of the stream. - * @throws InvalidMidiDataException if invalid data is encountered - * in the stream, or the stream is not supported. + * @param sequence the sequence to be loaded + * @throws InvalidMidiDataException if the sequence contains invalid MIDI + * data, or is not supported */ - public void setSequence(InputStream stream) throws IOException, InvalidMidiDataException; + void setSequence(Sequence sequence) throws InvalidMidiDataException; + /** + * Sets the current sequence on which the sequencer operates. The stream + * must point to MIDI file data. + *

+ * This method can be called even if the {@code Sequencer} is closed. + * + * @param stream stream containing MIDI file data + * @throws IOException if an I/O exception occurs during reading of the + * stream + * @throws InvalidMidiDataException if invalid data is encountered in the + * stream, or the stream is not supported + */ + void setSequence(InputStream stream) + throws IOException, InvalidMidiDataException; /** * Obtains the sequence on which the Sequencer is currently operating. - * - *

This method can be called even if the - * Sequencer is closed. + *

+ * This method can be called even if the {@code Sequencer} is closed. * - * @return the current sequence, or null if no sequence is currently set. + * @return the current sequence, or {@code null} if no sequence is currently + * set */ - public Sequence getSequence(); - + Sequence getSequence(); /** - * Starts playback of the MIDI data in the currently - * loaded sequence. - * Playback will begin from the current position. - * If the playback position reaches the loop end point, - * and the loop count is greater than 0, playback will - * resume at the loop start point for the number of - * repetitions set with setLoopCount. - * After that, or if the loop count is 0, playback will - * continue to play to the end of the sequence. + * Starts playback of the MIDI data in the currently loaded sequence. + * Playback will begin from the current position. If the playback position + * reaches the loop end point, and the loop count is greater than 0, + * playback will resume at the loop start point for the number of + * repetitions set with {@code setLoopCount}. After that, or if the loop + * count is 0, playback will continue to play to the end of the sequence. + *

+ * The implementation ensures that the synthesizer is brought to a + * consistent state when jumping to the loop start point by sending + * appropriate controllers, pitch bend, and program change events. * - *

The implementation ensures that the synthesizer - * is brought to a consistent state when jumping - * to the loop start point by sending appropriate - * controllers, pitch bend, and program change events. - * - * @throws IllegalStateException if the Sequencer is - * closed. - * + * @throws IllegalStateException if the {@code Sequencer} is closed * @see #setLoopStartPoint * @see #setLoopEndPoint * @see #setLoopCount * @see #stop */ - public void start(); - + void start(); /** - * Stops recording, if active, and playback of the currently loaded sequence, - * if any. + * Stops recording, if active, and playback of the currently loaded + * sequence, if any. * - * @throws IllegalStateException if the Sequencer is - * closed. - * + * @throws IllegalStateException if the {@code Sequencer} is closed * @see #start * @see #isRunning */ - public void stop(); - - - /** - * Indicates whether the Sequencer is currently running. The default is false. - * The Sequencer starts running when either {@link #start} or {@link #startRecording} - * is called. isRunning then returns true until playback of the - * sequence completes or {@link #stop} is called. - * @return true if the Sequencer is running, otherwise false - */ - public boolean isRunning(); - + void stop(); /** - * Starts recording and playback of MIDI data. Data is recorded to all enabled tracks, - * on the channel(s) for which they were enabled. Recording begins at the current position - * of the sequencer. Any events already in the track are overwritten for the duration - * of the recording session. Events from the currently loaded sequence, - * if any, are delivered to the sequencer's transmitter(s) along with messages - * received during recording. + * Indicates whether the Sequencer is currently running. The default is + * {@code false}. The Sequencer starts running when either{@link #start} or + * {@link #startRecording} is called. {@code isRunning} then returns + * {@code true} until playback of the sequence completes or {@link #stop} is + * called. + * + * @return {@code true} if the Sequencer is running, otherwise {@code false} + */ + boolean isRunning(); + + /** + * Starts recording and playback of MIDI data. Data is recorded to all + * enabled tracks, on the channel(s) for which they were enabled. Recording + * begins at the current position of the sequencer. Any events already in + * the track are overwritten for the duration of the recording session. + * Events from the currently loaded sequence, if any, are delivered to the + * sequencer's transmitter(s) along with messages received during recording. *

- * Note that tracks are not by default enabled for recording. In order to record MIDI data, - * at least one track must be specifically enabled for recording. + * Note that tracks are not by default enabled for recording. In order to + * record MIDI data, at least one track must be specifically enabled for + * recording. * - * @throws IllegalStateException if the Sequencer is - * closed. - * - * @see #startRecording + * @throws IllegalStateException if the {@code Sequencer} is closed * @see #recordEnable * @see #recordDisable */ - public void startRecording(); - + void startRecording(); /** - * Stops recording, if active. Playback of the current sequence continues. + * Stops recording, if active. Playback of the current sequence continues. * - * @throws IllegalStateException if the Sequencer is - * closed. - * + * @throws IllegalStateException if the {@code Sequencer} is closed * @see #startRecording * @see #isRecording */ - public void stopRecording(); - + void stopRecording(); /** - * Indicates whether the Sequencer is currently recording. The default is false. - * The Sequencer begins recording when {@link #startRecording} is called, - * and then returns true until {@link #stop} or {@link #stopRecording} - * is called. - * @return true if the Sequencer is recording, otherwise false + * Indicates whether the Sequencer is currently recording. The default is + * {@code false}. The Sequencer begins recording when + * {@link #startRecording} is called, and then returns {@code true} until + * {@link #stop} or {@link #stopRecording} is called. + * + * @return {@code true} if the Sequencer is recording, otherwise + * {@code false} */ - public boolean isRecording(); - + boolean isRecording(); /** - * Prepares the specified track for recording events received on a particular channel. - * Once enabled, a track will receive events when recording is active. - * @param track the track to which events will be recorded - * @param channel the channel on which events will be received. If -1 is specified - * for the channel value, the track will receive data from all channels. - * @throws IllegalArgumentException thrown if the track is not part of the current - * sequence. + * Prepares the specified track for recording events received on a + * particular channel. Once enabled, a track will receive events when + * recording is active. + * + * @param track the track to which events will be recorded + * @param channel the channel on which events will be received. If -1 is + * specified for the channel value, the track will receive data from + * all channels. + * @throws IllegalArgumentException thrown if the track is not part of the + * current sequence */ - public void recordEnable(Track track, int channel); - + void recordEnable(Track track, int channel); /** - * Disables recording to the specified track. Events will no longer be recorded - * into this track. - * @param track the track to disable for recording, or null to disable - * recording for all tracks. + * Disables recording to the specified track. Events will no longer be + * recorded into this track. + * + * @param track the track to disable for recording, or {@code null} to + * disable recording for all tracks */ - public void recordDisable(Track track); - + void recordDisable(Track track); /** - * Obtains the current tempo, expressed in beats per minute. The - * actual tempo of playback is the product of the returned value - * and the tempo factor. + * Obtains the current tempo, expressed in beats per minute. The actual + * tempo of playback is the product of the returned value and the tempo + * factor. * * @return the current tempo in beats per minute - * * @see #getTempoFactor * @see #setTempoInBPM(float) * @see #getTempoInMPQ */ - public float getTempoInBPM(); - + float getTempoInBPM(); /** - * Sets the tempo in beats per minute. The actual tempo of playback - * is the product of the specified value and the tempo factor. + * Sets the tempo in beats per minute. The actual tempo of playback is the + * product of the specified value and the tempo factor. * - * @param bpm desired new tempo in beats per minute + * @param bpm desired new tempo in beats per minute * @see #getTempoFactor * @see #setTempoInMPQ(float) * @see #getTempoInBPM */ - public void setTempoInBPM(float bpm); - + void setTempoInBPM(float bpm); /** - * Obtains the current tempo, expressed in microseconds per quarter - * note. The actual tempo of playback is the product of the returned - * value and the tempo factor. + * Obtains the current tempo, expressed in microseconds per quarter note. + * The actual tempo of playback is the product of the returned value and the + * tempo factor. * * @return the current tempo in microseconds per quarter note * @see #getTempoFactor * @see #setTempoInMPQ(float) * @see #getTempoInBPM */ - public float getTempoInMPQ(); - + float getTempoInMPQ(); /** - * Sets the tempo in microseconds per quarter note. The actual tempo - * of playback is the product of the specified value and the tempo - * factor. + * Sets the tempo in microseconds per quarter note. The actual tempo of + * playback is the product of the specified value and the tempo factor. * - * @param mpq desired new tempo in microseconds per quarter note. + * @param mpq desired new tempo in microseconds per quarter note * @see #getTempoFactor * @see #setTempoInBPM(float) * @see #getTempoInMPQ */ - public void setTempoInMPQ(float mpq); - + void setTempoInMPQ(float mpq); /** - * Scales the sequencer's actual playback tempo by the factor provided. - * The default is 1.0. A value of 1.0 represents the natural rate (the - * tempo specified in the sequence), 2.0 means twice as fast, etc. - * The tempo factor does not affect the values returned by - * {@link #getTempoInMPQ} and {@link #getTempoInBPM}. - * Those values indicate the tempo prior to scaling. + * Scales the sequencer's actual playback tempo by the factor provided. The + * default is 1.0. A value of 1.0 represents the natural rate (the tempo + * specified in the sequence), 2.0 means twice as fast, etc. The tempo + * factor does not affect the values returned by {@link #getTempoInMPQ} and + * {@link #getTempoInBPM}. Those values indicate the tempo prior to scaling. *

* Note that the tempo factor cannot be adjusted when external - * synchronization is used. In that situation, - * setTempoFactor always sets the tempo factor to 1.0. + * synchronization is used. In that situation, {@code setTempoFactor} always + * sets the tempo factor to 1.0. * - * @param factor the requested tempo scalar + * @param factor the requested tempo scalar * @see #getTempoFactor */ - public void setTempoFactor(float factor); - + void setTempoFactor(float factor); /** - * Returns the current tempo factor for the sequencer. The default is - * 1.0. + * Returns the current tempo factor for the sequencer. The default is 1.0. * - * @return tempo factor. + * @return tempo factor * @see #setTempoFactor(float) */ - public float getTempoFactor(); - + float getTempoFactor(); /** - * Obtains the length of the current sequence, expressed in MIDI ticks, - * or 0 if no sequence is set. + * Obtains the length of the current sequence, expressed in MIDI ticks, or 0 + * if no sequence is set. + * * @return length of the sequence in ticks */ - public long getTickLength(); - + long getTickLength(); /** - * Obtains the current position in the sequence, expressed in MIDI - * ticks. (The duration of a tick in seconds is determined both by - * the tempo and by the timing resolution stored in the - * {@link Sequence}.) + * Obtains the current position in the sequence, expressed in MIDI ticks. + * (The duration of a tick in seconds is determined both by the tempo and by + * the timing resolution stored in the {@link Sequence}.) * * @return current tick * @see #setTickPosition */ - public long getTickPosition(); - + long getTickPosition(); /** - * Sets the current sequencer position in MIDI ticks - * @param tick the desired tick position + * Sets the current sequencer position in MIDI ticks. + * + * @param tick the desired tick position * @see #getTickPosition */ - public void setTickPosition(long tick); - + void setTickPosition(long tick); /** - * Obtains the length of the current sequence, expressed in microseconds, - * or 0 if no sequence is set. - * @return length of the sequence in microseconds. + * Obtains the length of the current sequence, expressed in microseconds, or + * 0 if no sequence is set. + * + * @return length of the sequence in microseconds */ - public long getMicrosecondLength(); - + long getMicrosecondLength(); /** - * Obtains the current position in the sequence, expressed in - * microseconds. + * Obtains the current position in the sequence, expressed in microseconds. + * * @return the current position in microseconds * @see #setMicrosecondPosition */ - public long getMicrosecondPosition(); - + long getMicrosecondPosition(); /** - * Sets the current position in the sequence, expressed in microseconds - * @param microseconds desired position in microseconds + * Sets the current position in the sequence, expressed in microseconds. + * + * @param microseconds desired position in microseconds * @see #getMicrosecondPosition */ - public void setMicrosecondPosition(long microseconds); - + void setMicrosecondPosition(long microseconds); /** - * Sets the source of timing information used by this sequencer. - * The sequencer synchronizes to the master, which is the internal clock, - * MIDI clock, or MIDI time code, depending on the value of - * sync. The sync argument must be one - * of the supported modes, as returned by - * {@link #getMasterSyncModes}. + * Sets the source of timing information used by this sequencer. The + * sequencer synchronizes to the master, which is the internal clock, MIDI + * clock, or MIDI time code, depending on the value of {@code sync}. The + * {@code sync} argument must be one of the supported modes, as returned by + * {@link #getMasterSyncModes}. * - * @param sync the desired master synchronization mode - * + * @param sync the desired master synchronization mode * @see SyncMode#INTERNAL_CLOCK * @see SyncMode#MIDI_SYNC * @see SyncMode#MIDI_TIME_CODE * @see #getMasterSyncMode */ - public void setMasterSyncMode(SyncMode sync); - + void setMasterSyncMode(SyncMode sync); /** * Obtains the current master synchronization mode for this sequencer. * * @return the current master synchronization mode - * - * @see #setMasterSyncMode(Sequencer.SyncMode) + * @see #setMasterSyncMode(SyncMode) * @see #getMasterSyncModes */ - public SyncMode getMasterSyncMode(); - + SyncMode getMasterSyncMode(); /** * Obtains the set of master synchronization modes supported by this * sequencer. * * @return the available master synchronization modes - * * @see SyncMode#INTERNAL_CLOCK * @see SyncMode#MIDI_SYNC * @see SyncMode#MIDI_TIME_CODE * @see #getMasterSyncMode - * @see #setMasterSyncMode(Sequencer.SyncMode) + * @see #setMasterSyncMode(SyncMode) */ - public SyncMode[] getMasterSyncModes(); - + SyncMode[] getMasterSyncModes(); /** - * Sets the slave synchronization mode for the sequencer. - * This indicates the type of timing information sent by the sequencer - * to its receiver. The sync argument must be one - * of the supported modes, as returned by - * {@link #getSlaveSyncModes}. + * Sets the slave synchronization mode for the sequencer. This indicates the + * type of timing information sent by the sequencer to its receiver. The + * {@code sync} argument must be one of the supported modes, as returned by + * {@link #getSlaveSyncModes}. * - * @param sync the desired slave synchronization mode - * + * @param sync the desired slave synchronization mode * @see SyncMode#MIDI_SYNC * @see SyncMode#MIDI_TIME_CODE * @see SyncMode#NO_SYNC * @see #getSlaveSyncModes */ - public void setSlaveSyncMode(SyncMode sync); - + void setSlaveSyncMode(SyncMode sync); /** * Obtains the current slave synchronization mode for this sequencer. * * @return the current slave synchronization mode - * - * @see #setSlaveSyncMode(Sequencer.SyncMode) + * @see #setSlaveSyncMode(SyncMode) * @see #getSlaveSyncModes */ - public SyncMode getSlaveSyncMode(); - + SyncMode getSlaveSyncMode(); /** - * Obtains the set of slave synchronization modes supported by the sequencer. + * Obtains the set of slave synchronization modes supported by the + * sequencer. * * @return the available slave synchronization modes - * * @see SyncMode#MIDI_SYNC * @see SyncMode#MIDI_TIME_CODE * @see SyncMode#NO_SYNC */ - public SyncMode[] getSlaveSyncModes(); - + SyncMode[] getSlaveSyncModes(); /** - * Sets the mute state for a track. This method may fail for a number - * of reasons. For example, the track number specified may not be valid - * for the current sequence, or the sequencer may not support this functionality. - * An application which needs to verify whether this operation succeeded should - * follow this call with a call to {@link #getTrackMute}. + * Sets the mute state for a track. This method may fail for a number of + * reasons. For example, the track number specified may not be valid for the + * current sequence, or the sequencer may not support this functionality. An + * application which needs to verify whether this operation succeeded should + * follow this call with a call to {@link #getTrackMute}. * - * @param track the track number. Tracks in the current sequence are numbered - * from 0 to the number of tracks in the sequence minus 1. - * @param mute the new mute state for the track. true implies the - * track should be muted, false implies the track should be unmuted. + * @param track the track number. Tracks in the current sequence are + * numbered from 0 to the number of tracks in the sequence minus 1. + * @param mute the new mute state for the track. {@code true} implies the + * track should be muted, {@code false} implies the track should be + * unmuted. * @see #getSequence */ - public void setTrackMute(int track, boolean mute); - + void setTrackMute(int track, boolean mute); /** - * Obtains the current mute state for a track. The default mute - * state for all tracks which have not been muted is false. In any - * case where the specified track has not been muted, this method should - * return false. This applies if the sequencer does not support muting - * of tracks, and if the specified track index is not valid. + * Obtains the current mute state for a track. The default mute state for + * all tracks which have not been muted is false. In any case where the + * specified track has not been muted, this method should return false. This + * applies if the sequencer does not support muting of tracks, and if the + * specified track index is not valid. * - * @param track the track number. Tracks in the current sequence are numbered - * from 0 to the number of tracks in the sequence minus 1. - * @return true if muted, false if not. + * @param track the track number. Tracks in the current sequence are + * numbered from 0 to the number of tracks in the sequence minus 1. + * @return {@code true} if muted, {@code false} if not */ - public boolean getTrackMute(int track); + boolean getTrackMute(int track); /** - * Sets the solo state for a track. If solo is true - * only this track and other solo'd tracks will sound. If solo - * is false then only other solo'd tracks will sound, unless no - * tracks are solo'd in which case all un-muted tracks will sound. + * Sets the solo state for a track. If {@code solo} is {@code true} only + * this track and other solo'd tracks will sound. If {@code solo} is + * {@code false} then only other solo'd tracks will sound, unless no tracks + * are solo'd in which case all un-muted tracks will sound. *

- * This method may fail for a number - * of reasons. For example, the track number specified may not be valid - * for the current sequence, or the sequencer may not support this functionality. - * An application which needs to verify whether this operation succeeded should - * follow this call with a call to {@link #getTrackSolo}. + * This method may fail for a number of reasons. For example, the track + * number specified may not be valid for the current sequence, or the + * sequencer may not support this functionality. An application which needs + * to verify whether this operation succeeded should follow this call with a + * call to {@link #getTrackSolo}. * - * @param track the track number. Tracks in the current sequence are numbered - * from 0 to the number of tracks in the sequence minus 1. - * @param solo the new solo state for the track. true implies the - * track should be solo'd, false implies the track should not be solo'd. + * @param track the track number. Tracks in the current sequence are + * numbered from 0 to the number of tracks in the sequence minus 1. + * @param solo the new solo state for the track. {@code true} implies the + * track should be solo'd, {@code false} implies the track should + * not be solo'd. * @see #getSequence */ - public void setTrackSolo(int track, boolean solo); - + void setTrackSolo(int track, boolean solo); /** - * Obtains the current solo state for a track. The default mute - * state for all tracks which have not been solo'd is false. In any - * case where the specified track has not been solo'd, this method should - * return false. This applies if the sequencer does not support soloing - * of tracks, and if the specified track index is not valid. + * Obtains the current solo state for a track. The default mute state for + * all tracks which have not been solo'd is false. In any case where the + * specified track has not been solo'd, this method should return false. + * This applies if the sequencer does not support soloing of tracks, and if + * the specified track index is not valid. * - * @param track the track number. Tracks in the current sequence are numbered - * from 0 to the number of tracks in the sequence minus 1. - * @return true if solo'd, false if not. + * @param track the track number. Tracks in the current sequence are + * numbered from 0 to the number of tracks in the sequence minus 1. + * @return {@code true} if solo'd, {@code false} if not */ - public boolean getTrackSolo(int track); - + boolean getTrackSolo(int track); /** - * Registers a meta-event listener to receive - * notification whenever a meta-event is encountered in the sequence - * and processed by the sequencer. This method can fail if, for - * instance,this class of sequencer does not support meta-event - * notification. + * Registers a meta-event listener to receive notification whenever a + * meta-event is encountered in the sequence and processed by the sequencer. + * This method can fail if, for instance,this class of sequencer does not + * support meta-event notification. * - * @param listener listener to add - * @return true if the listener was successfully added, - * otherwise false - * + * @param listener listener to add + * @return {@code true} if the listener was successfully added, otherwise + * {@code false} * @see #removeMetaEventListener * @see MetaEventListener * @see MetaMessage */ - public boolean addMetaEventListener(MetaEventListener listener); - + boolean addMetaEventListener(MetaEventListener listener); /** - * Removes the specified meta-event listener from this sequencer's - * list of registered listeners, if in fact the listener is registered. + * Removes the specified meta-event listener from this sequencer's list of + * registered listeners, if in fact the listener is registered. * - * @param listener the meta-event listener to remove + * @param listener the meta-event listener to remove * @see #addMetaEventListener */ - public void removeMetaEventListener(MetaEventListener listener); - + void removeMetaEventListener(MetaEventListener listener); /** - * Registers a controller event listener to receive notification - * whenever the sequencer processes a control-change event of the - * requested type or types. The types are specified by the - * controllers argument, which should contain an array of - * MIDI controller numbers. (Each number should be between 0 and 127, - * inclusive. See the MIDI 1.0 Specification for the numbers that - * correspond to various types of controllers.) + * Registers a controller event listener to receive notification whenever + * the sequencer processes a control-change event of the requested type or + * types. The types are specified by the {@code controllers} argument, which + * should contain an array of MIDI controller numbers. (Each number should + * be between 0 and 127, inclusive. See the MIDI 1.0 Specification for the + * numbers that correspond to various types of controllers.) *

- * The returned array contains the MIDI controller - * numbers for which the listener will now receive events. - * Some sequencers might not support controller event notification, in - * which case the array has a length of 0. Other sequencers might - * support notification for some controllers but not all. - * This method may be invoked repeatedly. - * Each time, the returned array indicates all the controllers - * that the listener will be notified about, not only the controllers - * requested in that particular invocation. + * The returned array contains the MIDI controller numbers for which the + * listener will now receive events. Some sequencers might not support + * controller event notification, in which case the array has a length of 0. + * Other sequencers might support notification for some controllers but not + * all. This method may be invoked repeatedly. Each time, the returned array + * indicates all the controllers that the listener will be notified about, + * not only the controllers requested in that particular invocation. * - * @param listener the controller event listener to add to the list of - * registered listeners - * @param controllers the MIDI controller numbers for which change - * notification is requested - * @return the numbers of all the MIDI controllers whose changes will - * now be reported to the specified listener - * + * @param listener the controller event listener to add to the list of + * registered listeners + * @param controllers the MIDI controller numbers for which change + * notification is requested + * @return the numbers of all the MIDI controllers whose changes will now be + * reported to the specified listener * @see #removeControllerEventListener * @see ControllerEventListener */ - public int[] addControllerEventListener(ControllerEventListener listener, int[] controllers); - + int[] addControllerEventListener(ControllerEventListener listener, + int[] controllers); /** - * Removes a controller event listener's interest in one or more - * types of controller event. The controllers argument - * is an array of MIDI numbers corresponding to the controllers for - * which the listener should no longer receive change notifications. - * To completely remove this listener from the list of registered - * listeners, pass in null for controllers. - * The returned array contains the MIDI controller - * numbers for which the listener will now receive events. The - * array has a length of 0 if the listener will not receive - * change notifications for any controllers. + * Removes a controller event listener's interest in one or more types of + * controller event. The {@code controllers} argument is an array of MIDI + * numbers corresponding to the controllers for which the listener should no + * longer receive change notifications. To completely remove this listener + * from the list of registered listeners, pass in {@code null} for + * {@code controllers}. The returned array contains the MIDI controller + * numbers for which the listener will now receive events. The array has a + * length of 0 if the listener will not receive change notifications for any + * controllers. * - * @param listener old listener - * @param controllers the MIDI controller numbers for which change - * notification should be cancelled, or null to cancel - * for all controllers - * @return the numbers of all the MIDI controllers whose changes will - * now be reported to the specified listener - * + * @param listener old listener + * @param controllers the MIDI controller numbers for which change + * notification should be cancelled, or {@code null} to cancel for + * all controllers + * @return the numbers of all the MIDI controllers whose changes will now be + * reported to the specified listener * @see #addControllerEventListener */ - public int[] removeControllerEventListener(ControllerEventListener listener, int[] controllers); - + int[] removeControllerEventListener(ControllerEventListener listener, + int[] controllers); /** - * Sets the first MIDI tick that will be - * played in the loop. If the loop count is - * greater than 0, playback will jump to this - * point when reaching the loop end point. - * - *

A value of 0 for the starting point means the - * beginning of the loaded sequence. The starting - * point must be lower than or equal to the ending - * point, and it must fall within the size of the - * loaded sequence. + * Sets the first MIDI tick that will be played in the loop. If the loop + * count is greater than 0, playback will jump to this point when reaching + * the loop end point. + *

+ * A value of 0 for the starting point means the beginning of the loaded + * sequence. The starting point must be lower than or equal to the ending + * point, and it must fall within the size of the loaded sequence. + *

+ * A sequencer's loop start point defaults to start of the sequence. * - *

A sequencer's loop start point defaults to - * start of the sequence. - * - * @param tick the loop's starting position, - * in MIDI ticks (zero-based) - * @throws IllegalArgumentException if the requested - * loop start point cannot be set, usually because - * it falls outside the sequence's - * duration or because the start point is - * after the end point - * + * @param tick the loop's starting position, in MIDI ticks (zero-based) + * @throws IllegalArgumentException if the requested loop start point cannot + * be set, usually because it falls outside the sequence's duration + * or because the start point is after the end point * @see #setLoopEndPoint * @see #setLoopCount * @see #getLoopStartPoint * @see #start * @since 1.5 */ - public void setLoopStartPoint(long tick); - + void setLoopStartPoint(long tick); /** - * Obtains the start position of the loop, - * in MIDI ticks. + * Obtains the start position of the loop, in MIDI ticks. * - * @return the start position of the loop, - in MIDI ticks (zero-based) + * @return the start position of the loop, in MIDI ticks (zero-based) * @see #setLoopStartPoint * @since 1.5 */ - public long getLoopStartPoint(); - + long getLoopStartPoint(); /** - * Sets the last MIDI tick that will be played in - * the loop. If the loop count is 0, the loop end - * point has no effect and playback continues to + * Sets the last MIDI tick that will be played in the loop. If the loop + * count is 0, the loop end point has no effect and playback continues to * play when reaching the loop end point. - * - *

A value of -1 for the ending point - * indicates the last tick of the sequence. - * Otherwise, the ending point must be greater - * than or equal to the starting point, and it must - * fall within the size of the loaded sequence. + *

+ * A value of -1 for the ending point indicates the last tick of the + * sequence. Otherwise, the ending point must be greater than or equal to + * the starting point, and it must fall within the size of the loaded + * sequence. + *

+ * A sequencer's loop end point defaults to -1, meaning the end of the + * sequence. * - *

A sequencer's loop end point defaults to -1, - * meaning the end of the sequence. - * - * @param tick the loop's ending position, - * in MIDI ticks (zero-based), or - * -1 to indicate the final tick - * @throws IllegalArgumentException if the requested - * loop point cannot be set, usually because - * it falls outside the sequence's - * duration or because the ending point is - * before the starting point - * + * @param tick the loop's ending position, in MIDI ticks (zero-based), or + * -1 to indicate the final tick + * @throws IllegalArgumentException if the requested loop point cannot be + * set, usually because it falls outside the sequence's duration or + * because the ending point is before the starting point * @see #setLoopStartPoint * @see #setLoopCount * @see #getLoopEndPoint * @see #start * @since 1.5 */ - public void setLoopEndPoint(long tick); - + void setLoopEndPoint(long tick); /** - * Obtains the end position of the loop, - * in MIDI ticks. + * Obtains the end position of the loop, in MIDI ticks. * - * @return the end position of the loop, in MIDI - * ticks (zero-based), or -1 to indicate - * the end of the sequence + * @return the end position of the loop, in MIDI ticks (zero-based), or -1 + * to indicate the end of the sequence * @see #setLoopEndPoint * @since 1.5 */ - public long getLoopEndPoint(); - + long getLoopEndPoint(); /** - * Sets the number of repetitions of the loop for - * playback. - * When the playback position reaches the loop end point, - * it will loop back to the loop start point - * count times, after which playback will - * continue to play to the end of the sequence. + * Sets the number of repetitions of the loop for playback. When the + * playback position reaches the loop end point, it will loop back to the + * loop start point {@code count} times, after which playback will continue + * to play to the end of the sequence. *

- * If the current position when this method is invoked - * is greater than the loop end point, playback - * continues to the end of the sequence without looping, - * unless the loop end point is changed subsequently. + * If the current position when this method is invoked is greater than the + * loop end point, playback continues to the end of the sequence without + * looping, unless the loop end point is changed subsequently. *

- * A count value of 0 disables looping: - * playback will continue at the loop end point, and it - * will not loop back to the loop start point. + * A {@code count} value of 0 disables looping: playback will continue at + * the loop end point, and it will not loop back to the loop start point. * This is a sequencer's default. - * - *

If playback is stopped during looping, the - * current loop status is cleared; subsequent start - * requests are not affected by an interrupted loop - * operation. + *

+ * If playback is stopped during looping, the current loop status is + * cleared; subsequent start requests are not affected by an interrupted + * loop operation. * - * @param count the number of times playback should - * loop back from the loop's end position - * to the loop's start position, or - * {@link #LOOP_CONTINUOUSLY} - * to indicate that looping should - * continue until interrupted - * - * @throws IllegalArgumentException if count is - * negative and not equal to {@link #LOOP_CONTINUOUSLY} - * + * @param count the number of times playback should loop back from the + * loop's end position to the loop's start position, or + * {@link #LOOP_CONTINUOUSLY} to indicate that looping should + * continue until interrupted + * @throws IllegalArgumentException if {@code count} is negative and not + * equal to {@link #LOOP_CONTINUOUSLY} * @see #setLoopStartPoint * @see #setLoopEndPoint * @see #getLoopCount * @see #start * @since 1.5 */ - public void setLoopCount(int count); - + void setLoopCount(int count); /** - * Obtains the number of repetitions for - * playback. + * Obtains the number of repetitions for playback. * - * @return the number of loops after which - * playback plays to the end of the + * @return the number of loops after which playback plays to the end of the * sequence * @see #setLoopCount * @see #start * @since 1.5 */ - public int getLoopCount(); + int getLoopCount(); /** - * A SyncMode object represents one of the ways in which - * a MIDI sequencer's notion of time can be synchronized with a master - * or slave device. - * If the sequencer is being synchronized to a master, the - * sequencer revises its current time in response to messages from - * the master. If the sequencer has a slave, the sequencer - * similarly sends messages to control the slave's timing. + * A {@code SyncMode} object represents one of the ways in which a MIDI + * sequencer's notion of time can be synchronized with a master or slave + * device. If the sequencer is being synchronized to a master, the sequencer + * revises its current time in response to messages from the master. If the + * sequencer has a slave, the sequencer similarly sends messages to control + * the slave's timing. *

- * There are three predefined modes that specify possible masters - * for a sequencer: INTERNAL_CLOCK, - * MIDI_SYNC, and MIDI_TIME_CODE. The - * latter two work if the sequencer receives MIDI messages from - * another device. In these two modes, the sequencer's time gets reset - * based on system real-time timing clock messages or MIDI time code - * (MTC) messages, respectively. These two modes can also be used - * as slave modes, in which case the sequencer sends the corresponding - * types of MIDI messages to its receiver (whether or not the sequencer - * is also receiving them from a master). A fourth mode, - * NO_SYNC, is used to indicate that the sequencer should - * not control its receiver's timing. + * There are three predefined modes that specify possible masters for a + * sequencer: {@code INTERNAL_CLOCK}, {@code MIDI_SYNC}, and + * {@code MIDI_TIME_CODE}. The latter two work if the sequencer receives + * MIDI messages from another device. In these two modes, the sequencer's + * time gets reset based on system real-time timing clock messages or MIDI + * time code (MTC) messages, respectively. These two modes can also be used + * as slave modes, in which case the sequencer sends the corresponding types + * of MIDI messages to its receiver (whether or not the sequencer is also + * receiving them from a master). A fourth mode, {@code NO_SYNC}, is used to + * indicate that the sequencer should not control its receiver's timing. * - * @see Sequencer#setMasterSyncMode(Sequencer.SyncMode) - * @see Sequencer#setSlaveSyncMode(Sequencer.SyncMode) + * @see Sequencer#setMasterSyncMode(SyncMode) + * @see Sequencer#setSlaveSyncMode(SyncMode) */ - public static class SyncMode { + class SyncMode { /** * Synchronization mode name. @@ -779,27 +684,27 @@ /** * Constructs a synchronization mode. - * @param name name of the synchronization mode + * + * @param name name of the synchronization mode */ protected SyncMode(String name) { this.name = name; } - /** - * Determines whether two objects are equal. - * Returns true if the objects are identical - * @param obj the reference object with which to compare - * @return true if this object is the same as the - * obj argument, false otherwise + * Determines whether two objects are equal. Returns {@code true} if the + * objects are identical. + * + * @param obj the reference object with which to compare + * @return {@code true} if this object is the same as the {@code obj} + * argument, {@code false} otherwise */ public final boolean equals(Object obj) { return super.equals(obj); } - /** * Finalizes the hashcode method. */ @@ -808,10 +713,10 @@ return super.hashCode(); } - /** * Provides this synchronization mode's name as the string * representation of the mode. + * * @return the name of this synchronization mode */ public final String toString() { @@ -819,50 +724,41 @@ return name; } - /** - * A master synchronization mode that makes the sequencer get - * its timing information from its internal clock. This is not - * a legal slave sync mode. + * A master synchronization mode that makes the sequencer get its timing + * information from its internal clock. This is not a legal slave sync + * mode. */ public static final SyncMode INTERNAL_CLOCK = new SyncMode("Internal Clock"); - /** - * A master or slave synchronization mode that specifies the - * use of MIDI clock - * messages. If this mode is used as the master sync mode, - * the sequencer gets its timing information from system real-time - * MIDI clock messages. This mode only applies as the master sync - * mode for sequencers that are also MIDI receivers. If this is the - * slave sync mode, the sequencer sends system real-time MIDI clock - * messages to its receiver. MIDI clock messages are sent at a rate - * of 24 per quarter note. + * A master or slave synchronization mode that specifies the use of MIDI + * clock messages. If this mode is used as the master sync mode, the + * sequencer gets its timing information from system real-time MIDI + * clock messages. This mode only applies as the master sync mode for + * sequencers that are also MIDI receivers. If this is the slave sync + * mode, the sequencer sends system real-time MIDI clock messages to its + * receiver. MIDI clock messages are sent at a rate of 24 per quarter + * note. */ public static final SyncMode MIDI_SYNC = new SyncMode("MIDI Sync"); - /** - * A master or slave synchronization mode that specifies the - * use of MIDI Time Code. - * If this mode is used as the master sync mode, - * the sequencer gets its timing information from MIDI Time Code - * messages. This mode only applies as the master sync - * mode to sequencers that are also MIDI receivers. If this - * mode is used as the - * slave sync mode, the sequencer sends MIDI Time Code - * messages to its receiver. (See the MIDI 1.0 Detailed - * Specification for a description of MIDI Time Code.) + * A master or slave synchronization mode that specifies the use of MIDI + * Time Code. If this mode is used as the master sync mode, the + * sequencer gets its timing information from MIDI Time Code messages. + * This mode only applies as the master sync mode to sequencers that are + * also MIDI receivers. If this mode is used as the slave sync mode, the + * sequencer sends MIDI Time Code messages to its receiver. (See the + * MIDI 1.0 Detailed Specification for a description of MIDI Time Code.) */ public static final SyncMode MIDI_TIME_CODE = new SyncMode("MIDI Time Code"); - /** * A slave synchronization mode indicating that no timing information - * should be sent to the receiver. This is not a legal master sync - * mode. + * should be sent to the receiver. This is not a legal master sync mode. */ public static final SyncMode NO_SYNC = new SyncMode("No Timing"); - } // class SyncMode + } } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/midi/ShortMessage.java --- a/jdk/src/java.desktop/share/classes/javax/sound/midi/ShortMessage.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/ShortMessage.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -26,156 +26,158 @@ package javax.sound.midi; /** - * A ShortMessage contains a MIDI message that has at most - * two data bytes following its status byte. The types of MIDI message - * that satisfy this criterion are channel voice, channel mode, system common, - * and system real-time--in other words, everything except system exclusive - * and meta-events. The ShortMessage class provides methods - * for getting and setting the contents of the MIDI message. + * A {@code ShortMessage} contains a MIDI message that has at most two data + * bytes following its status byte. The types of MIDI message that satisfy this + * criterion are channel voice, channel mode, system common, and system + * real-time--in other words, everything except system exclusive and + * meta-events. The {@code ShortMessage} class provides methods for getting and + * setting the contents of the MIDI message. *

- * A number of ShortMessage methods have integer parameters by which - * you specify a MIDI status or data byte. If you know the numeric value, you - * can express it directly. For system common and system real-time messages, - * you can often use the corresponding fields of ShortMessage, such as - * {@link #SYSTEM_RESET SYSTEM_RESET}. For channel messages, - * the upper four bits of the status byte are specified by a command value and - * the lower four bits are specified by a MIDI channel number. To - * convert incoming MIDI data bytes that are in the form of Java's signed bytes, - * you can use the conversion code - * given in the {@link MidiMessage} class description. - * - * @see SysexMessage - * @see MetaMessage + * A number of {@code ShortMessage} methods have integer parameters by which you + * specify a MIDI status or data byte. If you know the numeric value, you can + * express it directly. For system common and system real-time messages, you can + * often use the corresponding fields of {@code ShortMessage}, such as + * {@link #SYSTEM_RESET SYSTEM_RESET}. For channel messages, the upper four bits + * of the status byte are specified by a command value and the lower four bits + * are specified by a MIDI channel number. To convert incoming MIDI data bytes + * that are in the form of Java's signed bytes, you can use the + * conversion code given in the + * {@link MidiMessage} class description. * * @author David Rivas * @author Kara Kytle * @author Florian Bomers + * @see SysexMessage + * @see MetaMessage */ - public class ShortMessage extends MidiMessage { - // Status byte defines - // System common messages /** * Status byte for MIDI Time Code Quarter Frame message (0xF1, or 241). + * * @see MidiMessage#getStatus */ public static final int MIDI_TIME_CODE = 0xF1; // 241 /** * Status byte for Song Position Pointer message (0xF2, or 242). + * * @see MidiMessage#getStatus */ public static final int SONG_POSITION_POINTER = 0xF2; // 242 /** * Status byte for MIDI Song Select message (0xF3, or 243). + * * @see MidiMessage#getStatus */ public static final int SONG_SELECT = 0xF3; // 243 /** * Status byte for Tune Request message (0xF6, or 246). + * * @see MidiMessage#getStatus */ public static final int TUNE_REQUEST = 0xF6; // 246 /** * Status byte for End of System Exclusive message (0xF7, or 247). + * * @see MidiMessage#getStatus */ public static final int END_OF_EXCLUSIVE = 0xF7; // 247 - // System real-time messages /** * Status byte for Timing Clock message (0xF8, or 248). + * * @see MidiMessage#getStatus */ public static final int TIMING_CLOCK = 0xF8; // 248 /** * Status byte for Start message (0xFA, or 250). + * * @see MidiMessage#getStatus */ public static final int START = 0xFA; // 250 /** * Status byte for Continue message (0xFB, or 251). + * * @see MidiMessage#getStatus */ public static final int CONTINUE = 0xFB; // 251 /** * Status byte for Stop message (0xFC, or 252). + * * @see MidiMessage#getStatus */ public static final int STOP = 0xFC; //252 /** * Status byte for Active Sensing message (0xFE, or 254). + * * @see MidiMessage#getStatus */ public static final int ACTIVE_SENSING = 0xFE; // 254 /** * Status byte for System Reset message (0xFF, or 255). + * * @see MidiMessage#getStatus */ public static final int SYSTEM_RESET = 0xFF; // 255 - // Channel voice message upper nibble defines /** - * Command value for Note Off message (0x80, or 128) + * Command value for Note Off message (0x80, or 128). */ public static final int NOTE_OFF = 0x80; // 128 /** - * Command value for Note On message (0x90, or 144) + * Command value for Note On message (0x90, or 144). */ public static final int NOTE_ON = 0x90; // 144 /** - * Command value for Polyphonic Key Pressure (Aftertouch) message (0xA0, or 160) + * Command value for Polyphonic Key Pressure (Aftertouch) message (0xA0, or + * 160). */ public static final int POLY_PRESSURE = 0xA0; // 160 /** - * Command value for Control Change message (0xB0, or 176) + * Command value for Control Change message (0xB0, or 176). */ public static final int CONTROL_CHANGE = 0xB0; // 176 /** - * Command value for Program Change message (0xC0, or 192) + * Command value for Program Change message (0xC0, or 192). */ public static final int PROGRAM_CHANGE = 0xC0; // 192 /** - * Command value for Channel Pressure (Aftertouch) message (0xD0, or 208) + * Command value for Channel Pressure (Aftertouch) message (0xD0, or 208). */ public static final int CHANNEL_PRESSURE = 0xD0; // 208 /** - * Command value for Pitch Bend message (0xE0, or 224) + * Command value for Pitch Bend message (0xE0, or 224). */ public static final int PITCH_BEND = 0xE0; // 224 - - // Instance variables - /** - * Constructs a new ShortMessage. The - * contents of the new message are guaranteed to specify - * a valid MIDI message. Subsequently, you may set the - * contents of the message using one of the setMessage - * methods. + * Constructs a new {@code ShortMessage}. The contents of the new message + * are guaranteed to specify a valid MIDI message. Subsequently, you may set + * the contents of the message using one of the {@code setMessage} methods. + * * @see #setMessage */ public ShortMessage() { @@ -188,14 +190,13 @@ } /** - * Constructs a new {@code ShortMessage} which represents a MIDI - * message that takes no data bytes. - * The contents of the message can be changed by using one of - * the {@code setMessage} methods. + * Constructs a new {@code ShortMessage} which represents a MIDI message + * that takes no data bytes. The contents of the message can be changed by + * using one of the {@code setMessage} methods. * - * @param status the MIDI status byte - * @throws InvalidMidiDataException if {@code status} does not specify - * a valid MIDI status byte for a message that requires no data bytes + * @param status the MIDI status byte + * @throws InvalidMidiDataException if {@code status} does not specify a + * valid MIDI status byte for a message that requires no data bytes * @see #setMessage(int) * @see #setMessage(int, int, int) * @see #setMessage(int, int, int, int) @@ -210,16 +211,15 @@ /** * Constructs a new {@code ShortMessage} which represents a MIDI message * that takes up to two data bytes. If the message only takes one data byte, - * the second data byte is ignored. If the message does not take - * any data bytes, both data bytes are ignored. - * The contents of the message can be changed by using one of - * the {@code setMessage} methods. + * the second data byte is ignored. If the message does not take any data + * bytes, both data bytes are ignored. The contents of the message can be + * changed by using one of the {@code setMessage} methods. * - * @param status the MIDI status byte - * @param data1 the first data byte - * @param data2 the second data byte + * @param status the MIDI status byte + * @param data1 the first data byte + * @param data2 the second data byte * @throws InvalidMidiDataException if the status byte or all data bytes - * belonging to the message do not specify a valid MIDI message + * belonging to the message do not specify a valid MIDI message * @see #setMessage(int) * @see #setMessage(int, int, int) * @see #setMessage(int, int, int, int) @@ -235,20 +235,19 @@ } /** - * Constructs a new {@code ShortMessage} which represents a channel - * MIDI message that takes up to two data bytes. If the message only takes - * one data byte, the second data byte is ignored. If the message does not - * take any data bytes, both data bytes are ignored. - * The contents of the message can be changed by using one of - * the {@code setMessage} methods. + * Constructs a new {@code ShortMessage} which represents a channel MIDI + * message that takes up to two data bytes. If the message only takes one + * data byte, the second data byte is ignored. If the message does not take + * any data bytes, both data bytes are ignored. The contents of the message + * can be changed by using one of the {@code setMessage} methods. * - * @param command the MIDI command represented by this message - * @param channel the channel associated with the message - * @param data1 the first data byte - * @param data2 the second data byte - * @throws InvalidMidiDataException if the command value, channel value - * or all data bytes belonging to the message do not specify - * a valid MIDI message + * @param command the MIDI command represented by this message + * @param channel the channel associated with the message + * @param data1 the first data byte + * @param data2 the second data byte + * @throws InvalidMidiDataException if the command value, channel value or + * all data bytes belonging to the message do not specify a valid + * MIDI message * @see #setMessage(int) * @see #setMessage(int, int, int) * @see #setMessage(int, int, int, int) @@ -264,12 +263,11 @@ setMessage(command, channel, data1, data2); } - /** - * Constructs a new ShortMessage. - * @param data an array of bytes containing the complete message. - * The message data may be changed using the setMessage - * method. + * Constructs a new {@code ShortMessage}. + * + * @param data an array of bytes containing the complete message. The + * message data may be changed using the {@code setMessage} method. * @see #setMessage */ // $$fb this should throw an Exception in case of an illegal message! @@ -279,12 +277,12 @@ super(data); } - /** * Sets the parameters for a MIDI message that takes no data bytes. - * @param status the MIDI status byte - * @throws InvalidMidiDataException if status does not - * specify a valid MIDI status byte for a message that requires no data bytes. + * + * @param status the MIDI status byte + * @throws InvalidMidiDataException if {@code status} does not specify a + * valid MIDI status byte for a message that requires no data bytes * @see #setMessage(int, int, int) * @see #setMessage(int, int, int, int) */ @@ -297,19 +295,17 @@ setMessage(status, 0, 0); } - /** - * Sets the parameters for a MIDI message that takes one or two data - * bytes. If the message takes only one data byte, the second data - * byte is ignored; if the message does not take any data bytes, both - * data bytes are ignored. + * Sets the parameters for a MIDI message that takes one or two data bytes. + * If the message takes only one data byte, the second data byte is ignored; + * if the message does not take any data bytes, both data bytes are ignored. * - * @param status the MIDI status byte - * @param data1 the first data byte - * @param data2 the second data byte - * @throws InvalidMidiDataException if the - * the status byte, or all data bytes belonging to the message, do - * not specify a valid MIDI message. + * @param status the MIDI status byte + * @param data1 the first data byte + * @param data2 the second data byte + * @throws InvalidMidiDataException if the the status byte, or all data + * bytes belonging to the message, do not specify a valid MIDI + * message * @see #setMessage(int, int, int, int) * @see #setMessage(int) */ @@ -345,22 +341,18 @@ } } - /** - * Sets the short message parameters for a channel message - * which takes up to two data bytes. If the message only - * takes one data byte, the second data byte is ignored; if - * the message does not take any data bytes, both data bytes - * are ignored. + * Sets the short message parameters for a channel message which takes up to + * two data bytes. If the message only takes one data byte, the second data + * byte is ignored; if the message does not take any data bytes, both data + * bytes are ignored. * - * @param command the MIDI command represented by this message - * @param channel the channel associated with the message - * @param data1 the first data byte - * @param data2 the second data byte - * @throws InvalidMidiDataException if the - * status byte or all data bytes belonging to the message, do - * not specify a valid MIDI message - * + * @param command the MIDI command represented by this message + * @param channel the channel associated with the message + * @param data1 the first data byte + * @param data2 the second data byte + * @throws InvalidMidiDataException if the status byte or all data bytes + * belonging to the message, do not specify a valid MIDI message * @see #setMessage(int, int, int) * @see #setMessage(int) * @see #getCommand @@ -379,12 +371,12 @@ setMessage((command & 0xF0) | (channel & 0x0F), data1, data2); } - /** - * Obtains the MIDI channel associated with this event. This method - * assumes that the event is a MIDI channel message; if not, the return - * value will not be meaningful. - * @return MIDI channel associated with the message. + * Obtains the MIDI channel associated with this event. This method assumes + * that the event is a MIDI channel message; if not, the return value will + * not be meaningful. + * + * @return MIDI channel associated with the message * @see #setMessage(int, int, int, int) */ public int getChannel() { @@ -392,11 +384,11 @@ return (getStatus() & 0x0F); } - /** - * Obtains the MIDI command associated with this event. This method - * assumes that the event is a MIDI channel message; if not, the return - * value will not be meaningful. + * Obtains the MIDI command associated with this event. This method assumes + * that the event is a MIDI channel message; if not, the return value will + * not be meaningful. + * * @return the MIDI command associated with this event * @see #setMessage(int, int, int, int) */ @@ -405,10 +397,10 @@ return (getStatus() & 0xF0); } - /** * Obtains the first data byte in the message. - * @return the value of the data1 field + * + * @return the value of the {@code data1} field * @see #setMessage(int, int, int) */ public int getData1() { @@ -418,10 +410,10 @@ return 0; } - /** * Obtains the second data byte in the message. - * @return the value of the data2 field + * + * @return the value of the {@code data2} field * @see #setMessage(int, int, int) */ public int getData2() { @@ -431,11 +423,11 @@ return 0; } - /** - * Creates a new object of the same class and with the same contents - * as this object. - * @return a clone of this instance. + * Creates a new object of the same class and with the same contents as this + * object. + * + * @return a clone of this instance */ public Object clone() { byte[] newData = new byte[length]; @@ -445,15 +437,15 @@ return msg; } - /** - * Retrieves the number of data bytes associated with a particular - * status byte value. - * @param status status byte value, which must represent a short MIDI message + * Retrieves the number of data bytes associated with a particular status + * byte value. + * + * @param status status byte value, which must represent a short MIDI + * message * @return data length in bytes (0, 1, or 2) - * @throws InvalidMidiDataException if the - * status argument does not represent the status byte for any - * short message + * @throws InvalidMidiDataException if the {@code status} argument does not + * represent the status byte for any short message */ protected final int getDataLength(int status) throws InvalidMidiDataException { // system common and system real-time messages diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/midi/Soundbank.java --- a/jdk/src/java.desktop/share/classes/javax/sound/midi/Soundbank.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/Soundbank.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -25,109 +25,101 @@ package javax.sound.midi; -import java.net.URL; - - /** - * A Soundbank contains a set of Instruments - * that can be loaded into a Synthesizer. - * Note that a Java Sound Soundbank is different from a MIDI bank. - * MIDI permits up to 16383 banks, each containing up to 128 instruments - * (also sometimes called programs, patches, or timbres). - * However, a Soundbank can contain 16383 times 128 instruments, - * because the instruments within a Soundbank are indexed by both - * a MIDI program number and a MIDI bank number (via a Patch - * object). Thus, a Soundbank can be thought of as a collection - * of MIDI banks. + * A {@code Soundbank} contains a set of {@code Instruments} that can be loaded + * into a {@code Synthesizer}. Note that a Java Sound {@code Soundbank} is + * different from a MIDI bank. MIDI permits up to 16383 banks, each containing + * up to 128 instruments (also sometimes called programs, patches, or timbres). + * However, a {@code Soundbank} can contain 16383 times 128 instruments, because + * the instruments within a {@code Soundbank} are indexed by both a MIDI program + * number and a MIDI bank number (via a {@code Patch} object). Thus, a + * {@code Soundbank} can be thought of as a collection of MIDI banks. + *

+ * {@code Soundbank} includes methods that return {@code String} objects + * containing the sound bank's name, manufacturer, version number, and + * description. The precise content and format of these strings is left to the + * implementor. *

- * Soundbank includes methods that return String - * objects containing the sound bank's name, manufacturer, version number, and - * description. The precise content and format of these strings is left - * to the implementor. - *

- * Different synthesizers use a variety of synthesis techniques. A common - * one is wavetable synthesis, in which a segment of recorded sound is - * played back, often with looping and pitch change. The Downloadable Sound - * (DLS) format uses segments of recorded sound, as does the Headspace Engine. - * Soundbanks and Instruments that are based on - * wavetable synthesis (or other uses of stored sound recordings) should - * typically implement the getResources() - * method to provide access to these recorded segments. This is optional, - * however; the method can return an zero-length array if the synthesis technique - * doesn't use sampled sound (FM synthesis and physical modeling are examples - * of such techniques), or if it does but the implementor chooses not to make the - * samples accessible. + * Different synthesizers use a variety of synthesis techniques. A common one is + * wavetable synthesis, in which a segment of recorded sound is played back, + * often with looping and pitch change. The Downloadable Sound (DLS) format uses + * segments of recorded sound, as does the Headspace Engine. {@code Soundbanks} + * and {@code Instruments} that are based on wavetable synthesis (or other uses + * of stored sound recordings) should typically implement the + * {@code getResources()} method to provide access to these recorded segments. + * This is optional, however; the method can return an zero-length array if the + * synthesis technique doesn't use sampled sound (FM synthesis and physical + * modeling are examples of such techniques), or if it does but the implementor + * chooses not to make the samples accessible. * + * @author David Rivas + * @author Kara Kytle * @see Synthesizer#getDefaultSoundbank * @see Synthesizer#isSoundbankSupported * @see Synthesizer#loadInstruments(Soundbank, Patch[]) * @see Patch * @see Instrument * @see SoundbankResource - * - * @author David Rivas - * @author Kara Kytle */ - public interface Soundbank { - /** * Obtains the name of the sound bank. - * @return a String naming the sound bank + * + * @return a {@code String} naming the sound bank */ - public String getName(); + String getName(); /** * Obtains the version string for the sound bank. - * @return a String that indicates the sound bank's version + * + * @return a {@code String} that indicates the sound bank's version */ - public String getVersion(); + String getVersion(); /** - * Obtains a string naming the company that provides the - * sound bank + * Obtains a {@code string} naming the company that provides the sound bank. + * * @return the vendor string */ - public String getVendor(); + String getVendor(); /** * Obtains a textual description of the sound bank, suitable for display. - * @return a String that describes the sound bank + * + * @return a {@code String} that describes the sound bank */ - public String getDescription(); - + String getDescription(); /** * Extracts a list of non-Instrument resources contained in the sound bank. - * @return an array of resources, excluding instruments. If the sound bank contains - * no resources (other than instruments), returns an array of length 0. + * + * @return an array of resources, excluding instruments. If the sound bank + * contains no resources (other than instruments), returns an array + * of length 0. */ - public SoundbankResource[] getResources(); - + SoundbankResource[] getResources(); /** * Obtains a list of instruments contained in this sound bank. - * @return an array of the Instruments in this - * SoundBank - * If the sound bank contains no instruments, returns an array of length 0. * + * @return an array of the {@code Instruments} in this {@code SoundBank}. If + * the sound bank contains no instruments, returns an array of + * length 0. * @see Synthesizer#getLoadedInstruments * @see #getInstrument(Patch) */ - public Instrument[] getInstruments(); + Instrument[] getInstruments(); /** - * Obtains an Instrument from the given Patch. - * @param patch a Patch object specifying the bank index - * and program change number - * @return the requested instrument, or null if the - * sound bank doesn't contain that instrument + * Obtains an {@code Instrument} from the given {@code Patch}. * + * @param patch a {@code Patch} object specifying the bank index and + * program change number + * @return the requested instrument, or {@code null} if the sound bank + * doesn't contain that instrument * @see #getInstruments * @see Synthesizer#loadInstruments(Soundbank, Patch[]) */ - public Instrument getInstrument(Patch patch); - - + Instrument getInstrument(Patch patch); } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/midi/SoundbankResource.java --- a/jdk/src/java.desktop/share/classes/javax/sound/midi/SoundbankResource.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/SoundbankResource.java Tue Aug 19 10:32:16 2014 -0700 @@ -25,81 +25,72 @@ package javax.sound.midi; +import javax.sound.sampled.AudioInputStream; + /** - * A SoundbankResource represents any audio resource stored - * in a {@link Soundbank}. Common soundbank resources include: + * A {@code SoundbankResource} represents any audio resource stored in a + * {@link Soundbank}. Common soundbank resources include: *

    - *
  • Instruments. An instrument may be specified in a variety of - * ways. However, all soundbanks have some mechanism for defining - * instruments. In doing so, they may reference other resources - * stored in the soundbank. Each instrument has a Patch - * which specifies the MIDI program and bank by which it may be - * referenced in MIDI messages. Instrument information may be - * stored in {@link Instrument} objects. - *
  • Audio samples. A sample typically is a sampled audio waveform - * which contains a short sound recording whose duration is a fraction of - * a second, or at most a few seconds. These audio samples may be - * used by a {@link Synthesizer} to synthesize sound in response to MIDI - * commands, or extracted for use by an application. - * (The terminology reflects musicians' use of the word "sample" to refer - * collectively to a series of contiguous audio samples or frames, rather than - * to a single, instantaneous sample.) - * The data class for an audio sample will be an object - * that encapsulates the audio sample data itself and information - * about how to interpret it (the format of the audio data), such - * as an {@link javax.sound.sampled.AudioInputStream}.
    • - *
  • Embedded sequences. A sound bank may contain built-in - * song data stored in a data object such as a {@link Sequence}. + *
  • Instruments. An instrument may be specified in a variety of ways. + * However, all soundbanks have some mechanism for defining instruments. In + * doing so, they may reference other resources stored in the soundbank. Each + * instrument has a {@code Patch} which specifies the MIDI program and bank by + * which it may be referenced in MIDI messages. Instrument information may be + * stored in {@link Instrument} objects.
    • + *
  • Audio samples. A sample typically is a sampled audio waveform which + * contains a short sound recording whose duration is a fraction of a second, or + * at most a few seconds. These audio samples may be used by a + * {@link Synthesizer} to synthesize sound in response to MIDI commands, or + * extracted for use by an application. (The terminology reflects musicians' use + * of the word "sample" to refer collectively to a series of contiguous audio + * samples or frames, rather than to a single, instantaneous sample.) The data + * class for an audio sample will be an object that encapsulates the audio + * sample data itself and information about how to interpret it (the format of + * the audio data), such as an {@link AudioInputStream}.
    • + *
  • Embedded sequences. A sound bank may contain built-in song data stored in + * a data object such as a {@link Sequence}.
    • *
- *

- * Synthesizers that use wavetable synthesis or related - * techniques play back the audio in a sample when - * synthesizing notes, often when emulating the real-world instrument that - * was originally recorded. However, there is not necessarily a one-to-one - * correspondence between the Instruments and samples - * in a Soundbank. A single Instrument can use - * multiple SoundbankResources (typically for notes of dissimilar pitch or - * brightness). Also, more than one Instrument can use the same - * sample. + * Synthesizers that use wavetable synthesis or related techniques play back the + * audio in a sample when synthesizing notes, often when emulating the + * real-world instrument that was originally recorded. However, there is not + * necessarily a one-to-one correspondence between the {@code Instruments} and + * samples in a {@code Soundbank}. A single {@code Instrument} can use multiple + * SoundbankResources (typically for notes of dissimilar pitch or brightness). + * Also, more than one {@code Instrument} can use the same sample. * * @author Kara Kytle */ - public abstract class SoundbankResource { - /** - * The sound bank that contains the SoundbankResources + * The sound bank that contains the {@code SoundbankResources}. */ private final Soundbank soundBank; - /** - * The name of the SoundbankResource + * The name of the {@code SoundbankResource}. */ private final String name; - /** * The class used to represent the sample's data. */ private final Class dataClass; - /** * The wavetable index. */ //private final int index; - /** - * Constructs a new SoundbankResource from the given sound bank - * and wavetable index. (Setting the SoundbankResource's name, - * sampled audio data, and instruments is a subclass responsibility.) - * @param soundBank the sound bank containing this SoundbankResource - * @param name the name of the sample - * @param dataClass the class used to represent the sample's data + * Constructs a new {@code SoundbankResource} from the given sound bank and + * wavetable index. (Setting the {@code SoundbankResource's} name, sampled + * audio data, and instruments is a subclass responsibility.) * + * @param soundBank the sound bank containing this + * {@code SoundbankResource} + * @param name the name of the sample + * @param dataClass the class used to represent the sample's data * @see #getSoundbank * @see #getName * @see #getDataClass @@ -112,65 +103,65 @@ this.dataClass = dataClass; } - /** - * Obtains the sound bank that contains this SoundbankResource. - * @return the sound bank in which this SoundbankResource is stored + * Obtains the sound bank that contains this {@code SoundbankResource}. + * + * @return the sound bank in which this {@code SoundbankResource} is stored */ public Soundbank getSoundbank() { return soundBank; } - /** - * Obtains the name of the resource. This should generally be a string + * Obtains the name of the resource. This should generally be a string * descriptive of the resource. + * * @return the instrument's name */ public String getName() { return name; } - /** - * Obtains the class used by this sample to represent its data. - * The object returned by getData will be of this - * class. If this SoundbankResource object does not support - * direct access to its data, returns null. - * @return the class used to represent the sample's data, or - * null if the data is not accessible + * Obtains the class used by this sample to represent its data. The object + * returned by {@code getData} will be of this class. If this + * {@code SoundbankResource} object does not support direct access to its + * data, returns {@code null}. + * + * @return the class used to represent the sample's data, or null if the + * data is not accessible */ public Class getDataClass() { return dataClass; } - /** - * Obtains the sampled audio that is stored in this SoundbankResource. - * The type of object returned depends on the implementation of the - * concrete class, and may be queried using getDataClass. + * Obtains the sampled audio that is stored in this + * {@code SoundbankResource}. The type of object returned depends on the + * implementation of the concrete class, and may be queried using + * {@code getDataClass}. + * * @return an object containing the sampled audio data * @see #getDataClass */ public abstract Object getData(); - /** - * Obtains the index of this SoundbankResource into the - * Soundbank's set of SoundbankResources. + * Obtains the index of this {@code SoundbankResource} into the + * {@code Soundbank's} set of {@code SoundbankResources}. + * * @return the wavetable index */ //public int getIndex() { // return index; //} - /** * Obtains a list of the instruments in the sound bank that use the - * SoundbankResource for sound synthesis. - * @return an array of Instruments that reference this - * SoundbankResource + * {@code SoundbankResource} for sound synthesis. * + * @return an array of {@code Instruments} that reference this + * {@code SoundbankResource} * @see Instrument#getSamples */ //public abstract Instrument[] getInstruments(); diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/midi/Synthesizer.java --- a/jdk/src/java.desktop/share/classes/javax/sound/midi/Synthesizer.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/Synthesizer.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -25,46 +25,43 @@ package javax.sound.midi; -import javax.sound.sampled.Control; - - /** - * A Synthesizer generates sound. This usually happens when one of - * the Synthesizer's {@link MidiChannel} objects receives a - * {@link MidiChannel#noteOn(int, int) noteOn} message, either - * directly or via the Synthesizer object. - * Many Synthesizers support Receivers, through which - * MIDI events can be delivered to the Synthesizer. - * In such cases, the Synthesizer typically responds by sending - * a corresponding message to the appropriate MidiChannel, or by - * processing the event itself if the event isn't one of the MIDI channel - * messages. + * A {@code Synthesizer} generates sound. This usually happens when one of the + * {@code Synthesizer}'s {@link MidiChannel} objects receives a + * {@link MidiChannel#noteOn(int, int) noteOn} message, either directly or via + * the {@code Synthesizer} object. Many {@code Synthesizer}s support + * {@code Receivers}, through which MIDI events can be delivered to the + * {@code Synthesizer}. In such cases, the {@code Synthesizer} typically + * responds by sending a corresponding message to the appropriate + * {@code MidiChannel}, or by processing the event itself if the event isn't one + * of the MIDI channel messages. *

- * The Synthesizer interface includes methods for loading and - * unloading instruments from soundbanks. An instrument is a specification for synthesizing a - * certain type of sound, whether that sound emulates a traditional instrument or is - * some kind of sound effect or other imaginary sound. A soundbank is a collection of instruments, organized - * by bank and program number (via the instrument's Patch object). - * Different Synthesizer classes might implement different sound-synthesis - * techniques, meaning that some instruments and not others might be compatible with a - * given synthesizer. - * Also, synthesizers may have a limited amount of memory for instruments, meaning - * that not every soundbank and instrument can be used by every synthesizer, even if - * the synthesis technique is compatible. - * To see whether the instruments from - * a certain soundbank can be played by a given synthesizer, invoke the - * {@link #isSoundbankSupported(Soundbank) isSoundbankSupported} method of - * Synthesizer. + * The {@code Synthesizer} interface includes methods for loading and unloading + * instruments from soundbanks. An instrument is a specification for + * synthesizing a certain type of sound, whether that sound emulates a + * traditional instrument or is some kind of sound effect or other imaginary + * sound. A soundbank is a collection of instruments, organized by bank and + * program number (via the instrument's {@code Patch} object). Different + * {@code Synthesizer} classes might implement different sound-synthesis + * techniques, meaning that some instruments and not others might be compatible + * with a given synthesizer. Also, synthesizers may have a limited amount of + * memory for instruments, meaning that not every soundbank and instrument can + * be used by every synthesizer, even if the synthesis technique is compatible. + * To see whether the instruments from a certain soundbank can be played by a + * given synthesizer, invoke the + * {@link #isSoundbankSupported(Soundbank) isSoundbankSupported} + * method of {@code Synthesizer}. *

* "Loading" an instrument means that that instrument becomes available for - * synthesizing notes. The instrument is loaded into the bank and - * program location specified by its Patch object. Loading does - * not necessarily mean that subsequently played notes will immediately have - * the sound of this newly loaded instrument. For the instrument to play notes, - * one of the synthesizer's MidiChannel objects must receive (or have received) - * a program-change message that causes that particular instrument's - * bank and program number to be selected. + * synthesizing notes. The instrument is loaded into the bank and program + * location specified by its {@code Patch} object. Loading does not necessarily + * mean that subsequently played notes will immediately have the sound of this + * newly loaded instrument. For the instrument to play notes, one of the + * synthesizer's {@code MidiChannel} objects must receive (or have received) a + * program-change message that causes that particular instrument's bank and + * program number to be selected. * + * @author Kara Kytle * @see MidiSystem#getSynthesizer * @see Soundbank * @see Instrument @@ -72,107 +69,103 @@ * @see Receiver * @see Transmitter * @see MidiDevice - * - * @author Kara Kytle */ public interface Synthesizer extends MidiDevice { - // SYNTHESIZER METHODS - /** - * Obtains the maximum number of notes that this synthesizer can sound simultaneously. + * Obtains the maximum number of notes that this synthesizer can sound + * simultaneously. + * * @return the maximum number of simultaneous notes * @see #getVoiceStatus */ - public int getMaxPolyphony(); - + int getMaxPolyphony(); /** * Obtains the processing latency incurred by this synthesizer, expressed in - * microseconds. This latency measures the worst-case delay between the - * time a MIDI message is delivered to the synthesizer and the time that the + * microseconds. This latency measures the worst-case delay between the time + * a MIDI message is delivered to the synthesizer and the time that the * synthesizer actually produces the corresponding result. *

- * Although the latency is expressed in microseconds, a synthesizer's actual measured - * delay may vary over a wider range than this resolution suggests. For example, - * a synthesizer might have a worst-case delay of a few milliseconds or more. + * Although the latency is expressed in microseconds, a synthesizer's actual + * measured delay may vary over a wider range than this resolution suggests. + * For example, a synthesizer might have a worst-case delay of a few + * milliseconds or more. * * @return the worst-case delay, in microseconds */ - public long getLatency(); - + long getLatency(); /** - * Obtains the set of MIDI channels controlled by this synthesizer. Each - * non-null element in the returned array is a MidiChannel that + * Obtains the set of MIDI channels controlled by this synthesizer. Each + * non-null element in the returned array is a {@code MidiChannel} that * receives the MIDI messages sent on that channel number. *

- * The MIDI 1.0 specification provides for 16 channels, so this - * method returns an array of at least 16 elements. However, if this synthesizer + * The MIDI 1.0 specification provides for 16 channels, so this method + * returns an array of at least 16 elements. However, if this synthesizer * doesn't make use of all 16 channels, some of the elements of the array - * might be null, so you should check each element - * before using it. - * @return an array of the MidiChannel objects managed by this - * Synthesizer. Some of the array elements may be null. + * might be {@code null}, so you should check each element before using it. + * + * @return an array of the {@code MidiChannel} objects managed by this + * {@code Synthesizer}. Some of the array elements may be + * {@code null}. */ - public MidiChannel[] getChannels(); - + MidiChannel[] getChannels(); /** - * Obtains the current status of the voices produced by this synthesizer. - * If this class of Synthesizer does not provide voice - * information, the returned array will always be of length 0. Otherwise, - * its length is always equal to the total number of voices, as returned by - * getMaxPolyphony(). (See the VoiceStatus class - * description for an explanation of synthesizer voices.) + * Obtains the current status of the voices produced by this synthesizer. If + * this class of {@code Synthesizer} does not provide voice information, the + * returned array will always be of length 0. Otherwise, its length is + * always equal to the total number of voices, as returned by + * {@code getMaxPolyphony()}. (See the {@code VoiceStatus} class description + * for an explanation of synthesizer voices.) * - * @return an array of VoiceStatus objects that supply - * information about the corresponding synthesizer voices + * @return an array of {@code VoiceStatus} objects that supply information + * about the corresponding synthesizer voices * @see #getMaxPolyphony * @see VoiceStatus */ - public VoiceStatus[] getVoiceStatus(); - + VoiceStatus[] getVoiceStatus(); /** * Informs the caller whether this synthesizer is capable of loading - * instruments from the specified soundbank. - * If the soundbank is unsupported, any attempts to load instruments from - * it will result in an IllegalArgumentException. - * @param soundbank soundbank for which support is queried - * @return true if the soundbank is supported, otherwise false + * instruments from the specified soundbank. If the soundbank is + * unsupported, any attempts to load instruments from it will result in an + * {@code IllegalArgumentException}. + * + * @param soundbank soundbank for which support is queried + * @return {@code true} if the soundbank is supported, otherwise + * {@code false} * @see #loadInstruments * @see #loadAllInstruments * @see #unloadInstruments * @see #unloadAllInstruments * @see #getDefaultSoundbank */ - public boolean isSoundbankSupported(Soundbank soundbank); - + boolean isSoundbankSupported(Soundbank soundbank); /** - * Makes a particular instrument available for synthesis. This instrument - * is loaded into the patch location specified by its Patch - * object, so that if a program-change message is - * received (or has been received) that causes that patch to be selected, - * subsequent notes will be played using the sound of - * instrument. If the specified instrument is already loaded, - * this method does nothing and returns true. + * Makes a particular instrument available for synthesis. This instrument is + * loaded into the patch location specified by its {@code Patch} object, so + * that if a program-change message is received (or has been received) that + * causes that patch to be selected, subsequent notes will be played using + * the sound of {@code instrument}. If the specified instrument is already + * loaded, this method does nothing and returns {@code true}. *

- * The instrument must be part of a soundbank - * that this Synthesizer supports. (To make sure, you can use - * the getSoundbank method of Instrument and the - * isSoundbankSupported method of Synthesizer.) - * @param instrument instrument to load - * @return true if the instrument is successfully loaded (or - * already had been), false if the instrument could not be - * loaded (for example, if the synthesizer has insufficient - * memory to load it) - * @throws IllegalArgumentException if this - * Synthesizer doesn't support the specified instrument's - * soundbank + * The instrument must be part of a soundbank that this {@code Synthesizer} + * supports. (To make sure, you can use the {@code getSoundbank} method of + * {@code Instrument} and the {@code isSoundbankSupported} method of + * {@code Synthesizer}.) + * + * @param instrument instrument to load + * @return {@code true} if the instrument is successfully loaded (or already + * had been), {@code false} if the instrument could not be loaded + * (for example, if the synthesizer has insufficient memory to load + * it) + * @throws IllegalArgumentException if this {@code Synthesizer} doesn't + * support the specified instrument's soundbank * @see #unloadInstrument * @see #loadInstruments * @see #loadAllInstruments @@ -180,138 +173,139 @@ * @see SoundbankResource#getSoundbank * @see MidiChannel#programChange(int, int) */ - public boolean loadInstrument(Instrument instrument); - + boolean loadInstrument(Instrument instrument); /** * Unloads a particular instrument. - * @param instrument instrument to unload - * @throws IllegalArgumentException if this - * Synthesizer doesn't support the specified instrument's - * soundbank + * + * @param instrument instrument to unload + * @throws IllegalArgumentException if this {@code Synthesizer} doesn't + * support the specified instrument's soundbank * @see #loadInstrument * @see #unloadInstruments * @see #unloadAllInstruments * @see #getLoadedInstruments * @see #remapInstrument */ - public void unloadInstrument(Instrument instrument); - + void unloadInstrument(Instrument instrument); /** - * Remaps an instrument. Instrument to takes the - * place of instrument from.
- * For example, if from was located at bank number 2, - * program number 11, remapping causes that bank and program location - * to be occupied instead by to.
- * If the function succeeds, instrument from is unloaded. - *

To cancel the remapping reload instrument from by - * invoking one of {@link #loadInstrument}, {@link #loadInstruments} - * or {@link #loadAllInstruments}. + * Remaps an instrument. Instrument {@code to} takes the place of instrument + * {@code from}. + *
+ * For example, if {@code from} was located at bank number 2, program number + * 11, remapping causes that bank and program location to be occupied + * instead by {@code to}. + *
+ * If the function succeeds, instrument {@code from} is unloaded. + *

+ * To cancel the remapping reload instrument {@code from} by invoking one of + * {@link #loadInstrument}, {@link #loadInstruments} or + * {@link #loadAllInstruments}. * - * @param from the Instrument object to be replaced - * @param to the Instrument object to be used in place - * of the old instrument, it should be loaded into the synthesizer - * @return true if the instrument successfully remapped, - * false if feature is not implemented by synthesizer - * @throws IllegalArgumentException if instrument - * from or instrument to aren't supported by - * synthesizer or if instrument to is not loaded - * @throws NullPointerException if from or - * to parameters have null value + * @param from the {@code Instrument} object to be replaced + * @param to the {@code Instrument} object to be used in place of the old + * instrument, it should be loaded into the synthesizer + * @return {@code true} if the instrument successfully remapped, + * {@code false} if feature is not implemented by synthesizer + * @throws IllegalArgumentException if instrument {@code from} or instrument + * {@code to} aren't supported by synthesizer or if instrument + * {@code to} is not loaded + * @throws NullPointerException if {@code from} or {@code to} parameters + * have null value * @see #loadInstrument * @see #loadInstruments * @see #loadAllInstruments */ - public boolean remapInstrument(Instrument from, Instrument to); - + boolean remapInstrument(Instrument from, Instrument to); /** - * Obtains the default soundbank for the synthesizer, if one exists. - * (Some synthesizers provide a default or built-in soundbank.) - * If a synthesizer doesn't have a default soundbank, instruments must - * be loaded explicitly from an external soundbank. - * @return default soundbank, or null if one does not exist. + * Obtains the default soundbank for the synthesizer, if one exists. (Some + * synthesizers provide a default or built-in soundbank.) If a synthesizer + * doesn't have a default soundbank, instruments must be loaded explicitly + * from an external soundbank. + * + * @return default soundbank, or {@code null} if one does not exist * @see #isSoundbankSupported */ - public Soundbank getDefaultSoundbank(); - + Soundbank getDefaultSoundbank(); /** - * Obtains a list of instruments that come with the synthesizer. These - * instruments might be built into the synthesizer, or they might be - * part of a default soundbank provided with the synthesizer, etc. + * Obtains a list of instruments that come with the synthesizer. These + * instruments might be built into the synthesizer, or they might be part of + * a default soundbank provided with the synthesizer, etc. *

- * Note that you don't use this method to find out which instruments are + * Note that you don't use this method to find out which instruments are * currently loaded onto the synthesizer; for that purpose, you use - * getLoadedInstruments(). - * Nor does the method indicate all the instruments that can be loaded onto - * the synthesizer; it only indicates the subset that come with the synthesizer. - * To learn whether another instrument can be loaded, you can invoke - * isSoundbankSupported(), and if the instrument's - * Soundbank is supported, you can try loading the instrument. + * {@code getLoadedInstruments()}. Nor does the method indicate all the + * instruments that can be loaded onto the synthesizer; it only indicates + * the subset that come with the synthesizer. To learn whether another + * instrument can be loaded, you can invoke {@code isSoundbankSupported()}, + * and if the instrument's {@code Soundbank} is supported, you can try + * loading the instrument. * - * @return list of available instruments. If the synthesizer - * has no instruments coming with it, an array of length 0 is returned. + * @return list of available instruments. If the synthesizer has no + * instruments coming with it, an array of length 0 is returned. * @see #getLoadedInstruments * @see #isSoundbankSupported(Soundbank) * @see #loadInstrument */ - public Instrument[] getAvailableInstruments(); - + Instrument[] getAvailableInstruments(); /** * Obtains a list of the instruments that are currently loaded onto this - * Synthesizer. + * {@code Synthesizer}. + * * @return a list of currently loaded instruments * @see #loadInstrument * @see #getAvailableInstruments * @see Soundbank#getInstruments */ - public Instrument[] getLoadedInstruments(); - + Instrument[] getLoadedInstruments(); /** - * Loads onto the Synthesizer all instruments contained - * in the specified Soundbank. - * @param soundbank the Soundbank whose are instruments are - * to be loaded - * @return true if the instruments are all successfully loaded (or - * already had been), false if any instrument could not be - * loaded (for example, if the Synthesizer had insufficient memory) + * Loads onto the {@code Synthesizer} all instruments contained in the + * specified {@code Soundbank}. + * + * @param soundbank the {@code Soundbank} whose are instruments are to be + * loaded + * @return {@code true} if the instruments are all successfully loaded (or + * already had been), {@code false} if any instrument could not be + * loaded (for example, if the {@code Synthesizer} had insufficient + * memory) * @throws IllegalArgumentException if the requested soundbank is - * incompatible with this synthesizer. + * incompatible with this synthesizer * @see #isSoundbankSupported * @see #loadInstrument * @see #loadInstruments */ - public boolean loadAllInstruments(Soundbank soundbank); - - + boolean loadAllInstruments(Soundbank soundbank); /** - * Unloads all instruments contained in the specified Soundbank. - * @param soundbank soundbank containing instruments to unload - * @throws IllegalArgumentException thrown if the soundbank is not supported. + * Unloads all instruments contained in the specified {@code Soundbank}. + * + * @param soundbank soundbank containing instruments to unload + * @throws IllegalArgumentException thrown if the soundbank is not supported * @see #isSoundbankSupported * @see #unloadInstrument * @see #unloadInstruments */ - public void unloadAllInstruments(Soundbank soundbank); - + void unloadAllInstruments(Soundbank soundbank); /** * Loads the instruments referenced by the specified patches, from the - * specified Soundbank. Each of the Patch objects - * indicates a bank and program number; the Instrument that - * has the matching Patch is loaded into that bank and program - * location. - * @param soundbank the Soundbank containing the instruments to load - * @param patchList list of patches for which instruments should be loaded - * @return true if the instruments are all successfully loaded (or - * already had been), false if any instrument could not be - * loaded (for example, if the Synthesizer had insufficient memory) - * @throws IllegalArgumentException thrown if the soundbank is not supported. + * specified {@code Soundbank}. Each of the {@code Patch} objects indicates + * a bank and program number; the {@code Instrument} that has the matching + * {@code Patch} is loaded into that bank and program location. + * + * @param soundbank the {@code Soundbank} containing the instruments to + * load + * @param patchList list of patches for which instruments should be loaded + * @return {@code true} if the instruments are all successfully loaded (or + * already had been), {@code false} if any instrument could not be + * loaded (for example, if the {@code Synthesizer} had insufficient + * memory) + * @throws IllegalArgumentException thrown if the soundbank is not supported * @see #isSoundbankSupported * @see Instrument#getPatch * @see #loadAllInstruments @@ -319,76 +313,76 @@ * @see Soundbank#getInstrument(Patch) * @see Sequence#getPatchList() */ - public boolean loadInstruments(Soundbank soundbank, Patch[] patchList); + boolean loadInstruments(Soundbank soundbank, Patch[] patchList); /** - * Unloads the instruments referenced by the specified patches, from the MIDI sound bank specified. - * @param soundbank soundbank containing instruments to unload - * @param patchList list of patches for which instruments should be unloaded - * @throws IllegalArgumentException thrown if the soundbank is not supported. + * Unloads the instruments referenced by the specified patches, from the + * MIDI sound bank specified. * + * @param soundbank soundbank containing instruments to unload + * @param patchList list of patches for which instruments should be + * unloaded + * @throws IllegalArgumentException thrown if the soundbank is not supported * @see #unloadInstrument * @see #unloadAllInstruments * @see #isSoundbankSupported * @see Instrument#getPatch * @see #loadInstruments */ - public void unloadInstruments(Soundbank soundbank, Patch[] patchList); - + void unloadInstruments(Soundbank soundbank, Patch[] patchList); // RECEIVER METHODS /** * Obtains the name of the receiver. + * * @return receiver name */ - // public abstract String getName(); - + // abstract String getName(); /** * Opens the receiver. + * * @throws MidiUnavailableException if the receiver is cannot be opened, - * usually because the MIDI device is in use by another application. - * @throws SecurityException if the receiver cannot be opened due to security - * restrictions. + * usually because the MIDI device is in use by another application. + * @throws SecurityException if the receiver cannot be opened due to + * security restrictions */ - // public abstract void open() throws MidiUnavailableException, SecurityException; - + // abstract void open() throws MidiUnavailableException, SecurityException; /** * Closes the receiver. */ - // public abstract void close(); - + // abstract void close(); /** * Sends a MIDI event to the receiver. - * @param event event to send. - * @throws IllegalStateException if the receiver is not open. + * + * @param event event to send + * @throws IllegalStateException if the receiver is not open */ - // public void send(MidiEvent event) throws IllegalStateException { + // void send(MidiEvent event) throws IllegalStateException { // // } - /** - * Obtains the set of controls supported by the - * element. If no controls are supported, returns an - * array of length 0. + * Obtains the set of controls supported by the element. If no controls are + * supported, returns an array of length 0. + * * @return set of controls */ // $$kk: 03.04.99: josh bloch recommends getting rid of this: // what can you really do with a set of untyped controls?? - // $$kk: 03.05.99: i am putting this back in. for one thing, + // $$kk: 03.05.99: i am putting this back in. for one thing, // you can check the length and know whether you should keep // looking.... - // public Control[] getControls(); + // Control[] getControls(); /** * Obtains the specified control. - * @param controlClass class of the requested control - * @return requested control object, or null if the - * control is not supported. + * + * @param controlClass class of the requested control + * @return requested control object, or null if the control is not supported */ - // public Control getControl(Class controlClass); + // Control getControl(Class controlClass); } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/midi/SysexMessage.java --- a/jdk/src/java.desktop/share/classes/javax/sound/midi/SysexMessage.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/SysexMessage.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -26,47 +26,47 @@ package javax.sound.midi; /** - * A SysexMessage object represents a MIDI system exclusive message. + * A {@code SysexMessage} object represents a MIDI system exclusive message. *

- * When a system exclusive message is read from a MIDI file, it always has - * a defined length. Data from a system exclusive message from a MIDI file - * should be stored in the data array of a SysexMessage as - * follows: the system exclusive message status byte (0xF0 or 0xF7), all - * message data bytes, and finally the end-of-exclusive flag (0xF7). - * The length reported by the SysexMessage object is therefore - * the length of the system exclusive data plus two: one byte for the status - * byte and one for the end-of-exclusive flag. + * When a system exclusive message is read from a MIDI file, it always has a + * defined length. Data from a system exclusive message from a MIDI file should + * be stored in the data array of a {@code SysexMessage} as follows: the system + * exclusive message status byte (0xF0 or 0xF7), all message data bytes, and + * finally the end-of-exclusive flag (0xF7). The length reported by the + * {@code SysexMessage} object is therefore the length of the system exclusive + * data plus two: one byte for the status byte and one for the end-of-exclusive + * flag. *

- * As dictated by the Standard MIDI Files specification, two status byte values are legal - * for a SysexMessage read from a MIDI file: + * As dictated by the Standard MIDI Files specification, two status byte values + * are legal for a {@code SysexMessage} read from a MIDI file: *

    *
  • 0xF0: System Exclusive message (same as in MIDI wire protocol)
    • *
  • 0xF7: Special System Exclusive message
    • *
- *

- * When Java Sound is used to handle system exclusive data that is being received - * using MIDI wire protocol, it should place the data in one or more - * SysexMessages. In this case, the length of the system exclusive data + * When Java Sound is used to handle system exclusive data that is being + * received using MIDI wire protocol, it should place the data in one or more + * {@code SysexMessages}. In this case, the length of the system exclusive data * is not known in advance; the end of the system exclusive data is marked by an * end-of-exclusive flag (0xF7) in the MIDI wire byte stream. *

    *
  • 0xF0: System Exclusive message (same as in MIDI wire protocol)
    • *
  • 0xF7: End of Exclusive (EOX)
    • *
- * The first SysexMessage object containing data for a particular system - * exclusive message should have the status value 0xF0. If this message contains all - * the system exclusive data - * for the message, it should end with the status byte 0xF7 (EOX). - * Otherwise, additional system exclusive data should be sent in one or more - * SysexMessages with a status value of 0xF7. The SysexMessage - * containing the last of the data for the system exclusive message should end with the - * value 0xF7 (EOX) to mark the end of the system exclusive message. + * The first {@code SysexMessage} object containing data for a particular system + * exclusive message should have the status value 0xF0. If this message contains + * all the system exclusive data for the message, it should end with the status + * byte 0xF7 (EOX). Otherwise, additional system exclusive data should be sent + * in one or more {@code SysexMessages} with a status value of 0xF7. The + * {@code SysexMessage} containing the last of the data for the system exclusive + * message should end with the value 0xF7 (EOX) to mark the end of the system + * exclusive message. *

- * If system exclusive data from SysexMessages objects is being transmitted - * using MIDI wire protocol, only the initial 0xF0 status byte, the system exclusive - * data itself, and the final 0xF7 (EOX) byte should be propagated; any 0xF7 status - * bytes used to indicate that a SysexMessage contains continuing system - * exclusive data should not be propagated via MIDI wire protocol. + * If system exclusive data from {@code SysexMessages} objects is being + * transmitted using MIDI wire protocol, only the initial 0xF0 status byte, the + * system exclusive data itself, and the final 0xF7 (EOX) byte should be + * propagated; any 0xF7 status bytes used to indicate that a + * {@code SysexMessage} contains continuing system exclusive data should not be + * propagated via MIDI wire protocol. * * @author David Rivas * @author Kara Kytle @@ -74,43 +74,36 @@ */ public class SysexMessage extends MidiMessage { - // Status byte defines - /** * Status byte for System Exclusive message (0xF0, or 240). + * * @see MidiMessage#getStatus */ public static final int SYSTEM_EXCLUSIVE = 0xF0; // 240 - /** - * Status byte for Special System Exclusive message (0xF7, or 247), which is used - * in MIDI files. It has the same value as END_OF_EXCLUSIVE, which - * is used in the real-time "MIDI wire" protocol. + * Status byte for Special System Exclusive message (0xF7, or 247), which is + * used in MIDI files. It has the same value as END_OF_EXCLUSIVE, which is + * used in the real-time "MIDI wire" protocol. + * * @see MidiMessage#getStatus */ public static final int SPECIAL_SYSTEM_EXCLUSIVE = 0xF7; // 247 - - // Instance variables - - - /* - * The data bytes for this system exclusive message. These are - * initialized to null and are set explicitly - * by {@link #setMessage(int, byte[], int, long) setMessage}. + /** + * The data bytes for this system exclusive message. These are initialized + * to {@code null} and are set explicitly by + * {@link #setMessage(int, byte[], int, long) setMessage}. */ //protected byte[] data = null; - /** - * Constructs a new SysexMessage. The - * contents of the new message are guaranteed to specify - * a valid MIDI message. Subsequently, you may set the - * contents of the message using one of the setMessage - * methods. + * Constructs a new {@code SysexMessage}. The contents of the new message + * are guaranteed to specify a valid MIDI message. Subsequently, you may set + * the contents of the message using one of the {@code setMessage} methods. + * * @see #setMessage */ public SysexMessage() { @@ -121,18 +114,17 @@ } /** - * Constructs a new {@code SysexMessage} and sets the data for - * the message. The first byte of the data array must be a valid system - * exclusive status byte (0xF0 or 0xF7). - * The contents of the message can be changed by using one of - * the {@code setMessage} methods. + * Constructs a new {@code SysexMessage} and sets the data for the message. + * The first byte of the data array must be a valid system exclusive status + * byte (0xF0 or 0xF7). The contents of the message can be changed by using + * one of the {@code setMessage} methods. * - * @param data the system exclusive message data including the status byte - * @param length the length of the valid message data in the array, - * including the status byte; it should be non-negative and less than - * or equal to {@code data.length} - * @throws InvalidMidiDataException if the parameter values - * do not specify a valid MIDI meta message. + * @param data the system exclusive message data including the status byte + * @param length the length of the valid message data in the array, + * including the status byte; it should be non-negative and less + * than or equal to {@code data.length} + * @throws InvalidMidiDataException if the parameter values do not specify a + * valid MIDI meta message. * @see #setMessage(byte[], int) * @see #setMessage(int, byte[], int) * @see #getData() @@ -146,17 +138,17 @@ /** * Constructs a new {@code SysexMessage} and sets the data for the message. - * The contents of the message can be changed by using one of - * the {@code setMessage} methods. + * The contents of the message can be changed by using one of the + * {@code setMessage} methods. * - * @param status the status byte for the message; it must be a valid system - * exclusive status byte (0xF0 or 0xF7) - * @param data the system exclusive message data (without the status byte) - * @param length the length of the valid message data in the array; - * it should be non-negative and less than or equal to - * {@code data.length} - * @throws InvalidMidiDataException if the parameter values - * do not specify a valid MIDI meta message. + * @param status the status byte for the message; it must be a valid system + * exclusive status byte (0xF0 or 0xF7) + * @param data the system exclusive message data (without the status byte) + * @param length the length of the valid message data in the array; it + * should be non-negative and less than or equal to + * {@code data.length} + * @throws InvalidMidiDataException if the parameter values do not specify a + * valid MIDI meta message * @see #setMessage(byte[], int) * @see #setMessage(int, byte[], int) * @see #getData() @@ -168,26 +160,24 @@ setMessage(status, data, length); } - /** - * Constructs a new SysexMessage. - * @param data an array of bytes containing the complete message. - * The message data may be changed using the setMessage - * method. + * Constructs a new {@code SysexMessage}. + * + * @param data an array of bytes containing the complete message. The + * message data may be changed using the {@code setMessage} method. * @see #setMessage */ protected SysexMessage(byte[] data) { super(data); } - /** - * Sets the data for the system exclusive message. The - * first byte of the data array must be a valid system - * exclusive status byte (0xF0 or 0xF7). - * @param data the system exclusive message data - * @param length the length of the valid message data in - * the array, including the status byte. + * Sets the data for the system exclusive message. The first byte of the + * data array must be a valid system exclusive status byte (0xF0 or 0xF7). + * + * @param data the system exclusive message data + * @param length the length of the valid message data in the array, + * including the status byte */ public void setMessage(byte[] data, int length) throws InvalidMidiDataException { int status = (data[0] & 0xFF); @@ -197,14 +187,14 @@ super.setMessage(data, length); } - /** * Sets the data for the system exclusive message. - * @param status the status byte for the message (0xF0 or 0xF7) - * @param data the system exclusive message data - * @param length the length of the valid message data in - * the array - * @throws InvalidMidiDataException if the status byte is invalid for a sysex message + * + * @param status the status byte for the message (0xF0 or 0xF7) + * @param data the system exclusive message data + * @param length the length of the valid message data in the array + * @throws InvalidMidiDataException if the status byte is invalid for a + * sysex message */ public void setMessage(int status, byte[] data, int length) throws InvalidMidiDataException { if ( (status != 0xF0) && (status != 0xF7) ) { @@ -225,11 +215,11 @@ } } - /** - * Obtains a copy of the data for the system exclusive message. - * The returned array of bytes does not include the status byte. - * @return array containing the system exclusive message data. + * Obtains a copy of the data for the system exclusive message. The returned + * array of bytes does not include the status byte. + * + * @return array containing the system exclusive message data */ public byte[] getData() { byte[] returnedArray = new byte[length - 1]; @@ -237,10 +227,10 @@ return returnedArray; } - /** - * Creates a new object of the same class and with the same contents - * as this object. + * Creates a new object of the same class and with the same contents as this + * object. + * * @return a clone of this instance */ public Object clone() { diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/midi/Track.java --- a/jdk/src/java.desktop/share/classes/javax/sound/midi/Track.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/Track.java Tue Aug 19 10:32:16 2014 -0700 @@ -25,41 +25,40 @@ package javax.sound.midi; -import java.util.Vector; import java.util.ArrayList; import java.util.HashSet; + import com.sun.media.sound.MidiUtils; /** - * A MIDI track is an independent stream of MIDI events (time-stamped MIDI - * data) that can be stored along with other tracks in a standard MIDI file. - * The MIDI specification allows only 16 channels of MIDI data, but tracks - * are a way to get around this limitation. A MIDI file can contain any number - * of tracks, each containing its own stream of up to 16 channels of MIDI data. + * A MIDI track is an independent stream of MIDI events (time-stamped MIDI data) + * that can be stored along with other tracks in a standard MIDI file. The MIDI + * specification allows only 16 channels of MIDI data, but tracks are a way to + * get around this limitation. A MIDI file can contain any number of tracks, + * each containing its own stream of up to 16 channels of MIDI data. *

- * A Track occupies a middle level in the hierarchy of data played - * by a {@link Sequencer}: sequencers play sequences, which contain tracks, - * which contain MIDI events. A sequencer may provide controls that mute - * or solo individual tracks. + * A {@code Track} occupies a middle level in the hierarchy of data played by a + * {@link Sequencer}: sequencers play sequences, which contain tracks, which + * contain MIDI events. A sequencer may provide controls that mute or solo + * individual tracks. *

* The timing information and resolution for a track is controlled by and stored - * in the sequence containing the track. A given Track - * is considered to belong to the particular {@link Sequence} that - * maintains its timing. For this reason, a new (empty) track is created by calling the - * {@link Sequence#createTrack} method, rather than by directly invoking a - * Track constructor. + * in the sequence containing the track. A given {@code Track} is considered to + * belong to the particular {@link Sequence} that maintains its timing. For this + * reason, a new (empty) track is created by calling the + * {@link Sequence#createTrack} method, rather than by directly invoking a + * {@code Track} constructor. *

- * The Track class provides methods to edit the track by adding - * or removing MidiEvent objects from it. These operations keep - * the event list in the correct time order. Methods are also - * included to obtain the track's size, in terms of either the number of events - * it contains or its duration in ticks. - * - * @see Sequencer#setTrackMute - * @see Sequencer#setTrackSolo + * The {@code Track} class provides methods to edit the track by adding or + * removing {@code MidiEvent} objects from it. These operations keep the event + * list in the correct time order. Methods are also included to obtain the + * track's size, in terms of either the number of events it contains or its + * duration in ticks. * * @author Kara Kytle * @author Florian Bomers + * @see Sequencer#setTrackMute + * @see Sequencer#setTrackSolo */ public class Track { @@ -73,10 +72,9 @@ private MidiEvent eotEvent; - /** - * Package-private constructor. Constructs a new, empty Track object, - * which initially contains one event, the meta-event End of Track. + * Package-private constructor. Constructs a new, empty Track object, which + * initially contains one event, the meta-event End of Track. */ Track() { // start with the end of track event @@ -87,14 +85,14 @@ } /** - * Adds a new event to the track. However, if the event is already - * contained in the track, it is not added again. The list of events - * is kept in time order, meaning that this event inserted at the - * appropriate place in the list, not necessarily at the end. + * Adds a new event to the track. However, if the event is already contained + * in the track, it is not added again. The list of events is kept in time + * order, meaning that this event inserted at the appropriate place in the + * list, not necessarily at the end. * - * @param event the event to add - * @return true if the event did not already exist in the - * track and was added, otherwise false + * @param event the event to add + * @return {@code true} if the event did not already exist in the track and + * was added, otherwise {@code false} */ public boolean add(MidiEvent event) { if (event == null) { @@ -176,12 +174,12 @@ return false; } - /** * Removes the specified event from the track. - * @param event the event to remove - * @return true if the event existed in the track and was removed, - * otherwise false + * + * @param event the event to remove + * @return {@code true} if the event existed in the track and was removed, + * otherwise {@code false} */ public boolean remove(MidiEvent event) { @@ -207,15 +205,14 @@ return false; } - /** * Obtains the event at the specified index. - * @param index the location of the desired event in the event vector - * @throws ArrayIndexOutOfBoundsException if the - * specified index is negative or not less than the current size of - * this track. + * + * @param index the location of the desired event in the event vector + * @return the event at the specified index + * @throws ArrayIndexOutOfBoundsException if the specified index is negative + * or not less than the current size of this track * @see #size - * @return the event at the specified index */ public MidiEvent get(int index) throws ArrayIndexOutOfBoundsException { try { @@ -227,9 +224,9 @@ } } - /** * Obtains the number of events in this track. + * * @return the size of the track's event vector */ public int size() { @@ -238,12 +235,12 @@ } } - /** - * Obtains the length of the track, expressed in MIDI ticks. (The - * duration of a tick in seconds is determined by the timing resolution - * of the Sequence containing this track, and also by - * the tempo of the music as set by the sequencer.) + * Obtains the length of the track, expressed in MIDI ticks. (The duration + * of a tick in seconds is determined by the timing resolution of the + * {@code Sequence} containing this track, and also by the tempo of the + * music as set by the sequencer.) + * * @return the duration, in ticks * @see Sequence#Sequence(float, int) * @see Sequencer#setTempoInBPM(float) @@ -271,5 +268,4 @@ throw new InvalidMidiDataException("cannot modify end of track message"); } } - } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/midi/Transmitter.java --- a/jdk/src/java.desktop/share/classes/javax/sound/midi/Transmitter.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/Transmitter.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2010, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -25,52 +25,49 @@ package javax.sound.midi; - /** - * A Transmitter sends {@link MidiEvent} objects to one or more - * {@link Receiver Receivers}. Common MIDI transmitters include sequencers - * and MIDI input ports. - * - * @see Receiver + * A {@code Transmitter} sends {@link MidiEvent} objects to one or more + * {@link Receiver Receivers}. Common MIDI transmitters include sequencers and + * MIDI input ports. * * @author Kara Kytle + * @see Receiver */ public interface Transmitter extends AutoCloseable { - /** * Sets the receiver to which this transmitter will deliver MIDI messages. * If a receiver is currently set, it is replaced with this one. - * @param receiver the desired receiver. + * + * @param receiver the desired receiver */ - public void setReceiver(Receiver receiver); - + void setReceiver(Receiver receiver); /** - * Obtains the current receiver to which this transmitter will deliver MIDI messages. - * @return the current receiver. If no receiver is currently set, - * returns null + * Obtains the current receiver to which this transmitter will deliver MIDI + * messages. + * + * @return the current receiver. If no receiver is currently set, returns + * {@code null}. */ - public Receiver getReceiver(); - + Receiver getReceiver(); /** * Indicates that the application has finished using the transmitter, and * that limited resources it requires may be released or made available. - * - *

If the creation of this Transmitter resulted in - * implicitly opening the underlying device, the device is - * implicitly closed by this method. This is true unless the device is - * kept open by other Receiver or Transmitter - * instances that opened the device implicitly, and unless the device - * has been opened explicitly. If the device this - * Transmitter is retrieved from is closed explicitly - * by calling {@link MidiDevice#close MidiDevice.close}, the - * Transmitter is closed, too. For a detailed - * description of open/close behaviour see the class description - * of {@link javax.sound.midi.MidiDevice MidiDevice}. + *

+ * If the creation of this {@code Transmitter} resulted in implicitly + * opening the underlying device, the device is implicitly closed by this + * method. This is true unless the device is kept open by other + * {@code Receiver} or {@code Transmitter} instances that opened the device + * implicitly, and unless the device has been opened explicitly. If the + * device this {@code Transmitter} is retrieved from is closed explicitly by + * calling {@link MidiDevice#close MidiDevice.close}, the + * {@code Transmitter} is closed, too. For a detailed description of + * open/close behaviour see the class description of + * {@link MidiDevice MidiDevice}. * * @see javax.sound.midi.MidiSystem#getTransmitter */ - public void close(); + void close(); } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/midi/VoiceStatus.java --- a/jdk/src/java.desktop/share/classes/javax/sound/midi/VoiceStatus.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/VoiceStatus.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1998, 2002, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -25,93 +25,83 @@ package javax.sound.midi; - /** - * A VoiceStatus object contains information about the current - * status of one of the voices produced by a {@link Synthesizer}. + * A {@code VoiceStatus} object contains information about the current status of + * one of the voices produced by a {@link Synthesizer}. *

* MIDI synthesizers are generally capable of producing some maximum number of - * simultaneous notes, also referred to as voices. A voice is a stream - * of successive single notes, and the process of assigning incoming MIDI notes to - * specific voices is known as voice allocation. - * However, the voice-allocation algorithm and the contents of each voice are - * normally internal to a MIDI synthesizer and hidden from outside view. One can, of - * course, learn from MIDI messages which notes the synthesizer is playing, and - * one might be able deduce something about the assignment of notes to voices. - * But MIDI itself does not provide a means to report which notes a - * synthesizer has assigned to which voice, nor even to report how many voices - * the synthesizer is capable of synthesizing. + * simultaneous notes, also referred to as voices. A voice is a stream of + * successive single notes, and the process of assigning incoming MIDI notes to + * specific voices is known as voice allocation. However, the voice-allocation + * algorithm and the contents of each voice are normally internal to a MIDI + * synthesizer and hidden from outside view. One can, of course, learn from MIDI + * messages which notes the synthesizer is playing, and one might be able deduce + * something about the assignment of notes to voices. But MIDI itself does not + * provide a means to report which notes a synthesizer has assigned to which + * voice, nor even to report how many voices the synthesizer is capable of + * synthesizing. *

- * In Java Sound, however, a - * Synthesizer class can expose the contents of its voices through its - * {@link Synthesizer#getVoiceStatus() getVoiceStatus()} method. - * This behavior is recommended but optional; - * synthesizers that don't expose their voice allocation simply return a - * zero-length array. A Synthesizer that does report its voice status - * should maintain this information at - * all times for all of its voices, whether they are currently sounding or - * not. In other words, a given type of Synthesizer always has a fixed - * number of voices, equal to the maximum number of simultaneous notes it is - * capable of sounding. + * In Java Sound, however, a {@code Synthesizer} class can expose the contents + * of its voices through its + * {@link Synthesizer#getVoiceStatus() getVoiceStatus()} method. This behavior + * is recommended but optional; synthesizers that don't expose their voice + * allocation simply return a zero-length array. A {@code Synthesizer} that does + * report its voice status should maintain this information at all times for all + * of its voices, whether they are currently sounding or not. In other words, a + * given type of {@code Synthesizer} always has a fixed number of voices, equal + * to the maximum number of simultaneous notes it is capable of sounding. *

- * - * If the voice is not currently processing a MIDI note, it - * is considered inactive. A voice is inactive when it has - * been given no note-on commands, or when every note-on command received has - * been terminated by a corresponding note-off (or by an "all notes off" - * message). For example, this happens when a synthesizer capable of playing 16 - * simultaneous notes is told to play a four-note chord; only - * four voices are active in this case (assuming no earlier notes are still playing). - * Usually, a voice whose status is reported as active is producing audible sound, but this - * is not always true; it depends on the details of the instrument (that - * is, the synthesis algorithm) and how long the note has been going on. - * For example, a voice may be synthesizing the sound of a single hand-clap. Because - * this sound dies away so quickly, it may become inaudible before a note-off - * message is received. In such a situation, the voice is still considered active - * even though no sound is currently being produced. + * If the voice is not currently processing + * a MIDI note, it is considered inactive. A voice is inactive when it has been + * given no note-on commands, or when every note-on command received has been + * terminated by a corresponding note-off (or by an "all notes off" message). + * For example, this happens when a synthesizer capable of playing 16 + * simultaneous notes is told to play a four-note chord; only four voices are + * active in this case (assuming no earlier notes are still playing). Usually, a + * voice whose status is reported as active is producing audible sound, but this + * is not always true; it depends on the details of the instrument (that is, the + * synthesis algorithm) and how long the note has been going on. For example, a + * voice may be synthesizing the sound of a single hand-clap. Because this sound + * dies away so quickly, it may become inaudible before a note-off message is + * received. In such a situation, the voice is still considered active even + * though no sound is currently being produced. *

- * Besides its active or inactive status, the VoiceStatus class - * provides fields that reveal the voice's current MIDI channel, bank and - * program number, MIDI note number, and MIDI volume. All of these can - * change during the course of a voice. While the voice is inactive, each - * of these fields has an unspecified value, so you should check the active - * field first. - * - * @see Synthesizer#getMaxPolyphony - * @see Synthesizer#getVoiceStatus + * Besides its active or inactive status, the {@code VoiceStatus} class provides + * fields that reveal the voice's current MIDI channel, bank and program number, + * MIDI note number, and MIDI volume. All of these can change during the course + * of a voice. While the voice is inactive, each of these fields has an + * unspecified value, so you should check the active field first. * * @author David Rivas * @author Kara Kytle + * @see Synthesizer#getMaxPolyphony + * @see Synthesizer#getVoiceStatus */ - public class VoiceStatus { - /** - * Indicates whether the voice is currently processing a MIDI note. - * See the explanation of - * active and inactive voices. + * Indicates whether the voice is currently processing a MIDI note. See the + * explanation of + * active and inactive voices. */ public boolean active = false; - /** - * The MIDI channel on which this voice is playing. The value is a - * zero-based channel number if the voice is active, or - * unspecified if the voice is inactive. + * The MIDI channel on which this voice is playing. The value is a + * zero-based channel number if the voice is active, or unspecified if the + * voice is inactive. * * @see MidiChannel * @see #active */ public int channel = 0; - /** * The bank number of the instrument that this voice is currently using. * This is a number dictated by the MIDI bank-select message; it does not - * refer to a SoundBank object. - * The value ranges from 0 to 16383 if the voice is active, and is - * unspecified if the voice is inactive. + * refer to a {@code SoundBank} object. The value ranges from 0 to 16383 if + * the voice is active, and is unspecified if the voice is inactive. + * * @see Patch * @see Soundbank * @see #active @@ -119,11 +109,10 @@ */ public int bank = 0; - /** * The program number of the instrument that this voice is currently using. - * The value ranges from 0 to 127 if the voice is active, and is - * unspecified if the voice is inactive. + * The value ranges from 0 to 127 if the voice is active, and is unspecified + * if the voice is inactive. * * @see MidiChannel#getProgram * @see Patch @@ -131,28 +120,24 @@ */ public int program = 0; - /** - * The MIDI note that this voice is playing. The range for an active voice - * is from 0 to 127 in semitones, with 60 referring to Middle C. - * The value is unspecified if the voice is inactive. + * The MIDI note that this voice is playing. The range for an active voice + * is from 0 to 127 in semitones, with 60 referring to Middle C. The value + * is unspecified if the voice is inactive. * * @see MidiChannel#noteOn * @see #active */ public int note = 0; - /** - * The current MIDI volume level for the voice. - * The value ranges from 0 to 127 if the voice is active, and is - * unspecified if the voice is inactive. + * The current MIDI volume level for the voice. The value ranges from 0 to + * 127 if the voice is active, and is unspecified if the voice is inactive. *

- * Note that this value does not necessarily reflect - * the instantaneous level of the sound produced by this - * voice; that level is the result of many contributing - * factors, including the current instrument and the - * shape of the amplitude envelope it produces. + * Note that this value does not necessarily reflect the instantaneous level + * of the sound produced by this voice; that level is the result of many + * contributing factors, including the current instrument and the shape of + * the amplitude envelope it produces. * * @see #active */ diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/midi/spi/MidiFileReader.java --- a/jdk/src/java.desktop/share/classes/javax/sound/midi/spi/MidiFileReader.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/spi/MidiFileReader.java Tue Aug 19 10:32:16 2014 -0700 @@ -26,13 +26,13 @@ package javax.sound.midi.spi; import java.io.File; +import java.io.IOException; import java.io.InputStream; -import java.io.IOException; import java.net.URL; +import javax.sound.midi.InvalidMidiDataException; import javax.sound.midi.MidiFileFormat; import javax.sound.midi.Sequence; -import javax.sound.midi.InvalidMidiDataException; /** * A {@code MidiFileReader} supplies MIDI file-reading services. Classes @@ -106,7 +106,7 @@ * @param stream the input stream from which the {@code Sequence} should * be constructed * @return a {@code Sequence} object based on the MIDI file data contained - * in the input stream. + * in the input stream * @throws InvalidMidiDataException if the stream does not point to valid * MIDI file data recognized by the system * @throws IOException if an I/O exception occurs diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/midi/spi/SoundbankReader.java --- a/jdk/src/java.desktop/share/classes/javax/sound/midi/spi/SoundbankReader.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/spi/SoundbankReader.java Tue Aug 19 10:32:16 2014 -0700 @@ -32,12 +32,12 @@ import javax.sound.midi.InvalidMidiDataException; import javax.sound.midi.Soundbank; +import javax.sound.midi.Synthesizer; /** * A {@code SoundbankReader} supplies soundbank file-reading services. Concrete * subclasses of {@code SoundbankReader} parse a given soundbank file, producing - * a {@link javax.sound.midi.Soundbank} object that can be loaded into a - * {@link javax.sound.midi.Synthesizer}. + * a {@link Soundbank} object that can be loaded into a {@link Synthesizer}. * * @since 1.3 * @author Kara Kytle @@ -47,7 +47,7 @@ /** * Obtains a soundbank object from the URL provided. * - * @param url URL representing the soundbank. + * @param url URL representing the soundbank * @return soundbank object * @throws InvalidMidiDataException if the URL does not point to valid MIDI * soundbank data recognized by this soundbank reader diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/sampled/AudioSystem.java --- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/AudioSystem.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/AudioSystem.java Tue Aug 19 10:32:16 2014 -0700 @@ -26,19 +26,19 @@ package javax.sound.sampled; import java.io.File; +import java.io.IOException; import java.io.InputStream; -import java.io.IOException; import java.io.OutputStream; import java.net.URL; - +import java.util.ArrayList; import java.util.HashSet; import java.util.List; +import java.util.Properties; import java.util.Set; import java.util.Vector; -import java.util.ArrayList; +import javax.sound.sampled.spi.AudioFileReader; import javax.sound.sampled.spi.AudioFileWriter; -import javax.sound.sampled.spi.AudioFileReader; import javax.sound.sampled.spi.FormatConversionProvider; import javax.sound.sampled.spi.MixerProvider; @@ -60,14 +60,14 @@ *

* Properties can be used to specify the default mixer for specific line types. * Both system properties and a properties file are considered. The - * {@code sound.properties} properties file is read from an - * implementation-specific location (typically it is the {@code lib} directory - * in the Java installation directory). If a property exists both as a system - * property and in the properties file, the system property takes precedence. - * If none is specified, a suitable default is chosen among the available - * devices. The syntax of the properties file is specified in - * {@link java.util.Properties#load(InputStream) Properties.load}. The following - * table lists the available property keys and which methods consider them: + * "sound.properties" properties file is read from an implementation-specific + * location (typically it is the {@code lib} directory in the Java installation + * directory). If a property exists both as a system property and in the + * properties file, the system property takes precedence. If none is specified, + * a suitable default is chosen among the available devices. The syntax of the + * properties file is specified in + * {@link Properties#load(InputStream) Properties.load}. The following table + * lists the available property keys and which methods consider them: * * * @@ -100,12 +100,11 @@ * * The property value consists of the provider class name and the mixer name, * separated by the hash mark ("#"). The provider class name is the - * fully-qualified name of a concrete - * {@link javax.sound.sampled.spi.MixerProvider mixer provider} class. The mixer - * name is matched against the {@code String} returned by the {@code getName} - * method of {@code Mixer.Info}. Either the class name, or the mixer name may be - * omitted. If only the class name is specified, the trailing hash mark is - * optional. + * fully-qualified name of a concrete {@link MixerProvider mixer provider} + * class. The mixer name is matched against the {@code String} returned by the + * {@code getName} method of {@code Mixer.Info}. Either the class name, or the + * mixer name may be omitted. If only the class name is specified, the trailing + * hash mark is optional. *

* If the provider class is specified, and it can be successfully retrieved from * the installed providers, the list of {@code Mixer.Info} objects is retrieved @@ -1324,10 +1323,9 @@ * Obtains the set of format converters (codecs, transcoders, etc.) that are * currently installed on the system. * - * @return an array of {@link javax.sound.sampled.spi.FormatConversionProvider - * FormatConversionProvider} objects representing the available - * format converters. If no format converters readers are available - * on the system, an array of length 0 is returned. + * @return an array of {@link FormatConversionProvider} objects representing + * the available format converters. If no format converters readers + * are available on the system, an array of length 0 is returned. */ @SuppressWarnings("unchecked") private static List getFormatConversionProviders() { @@ -1338,10 +1336,9 @@ * Obtains the set of audio file readers that are currently installed on the * system. * - * @return a List of {@link javax.sound.sampled.spi.AudioFileReader - * AudioFileReader} objects representing the installed audio file - * readers. If no audio file readers are available on the system, an - * empty List is returned. + * @return a List of {@link AudioFileReader} objects representing the + * installed audio file readers. If no audio file readers are + * available on the system, an empty List is returned. */ @SuppressWarnings("unchecked") private static List getAudioFileReaders() { @@ -1352,10 +1349,9 @@ * Obtains the set of audio file writers that are currently installed on the * system. * - * @return a List of {@link javax.sound.sampled.spi.AudioFileWriter - * AudioFileWriter} objects representing the available audio file - * writers. If no audio file writers are available on the system, an - * empty List is returned. + * @return a List of {@link AudioFileWriter} objects representing the + * available audio file writers. If no audio file writers are + * available on the system, an empty List is returned. */ @SuppressWarnings("unchecked") private static List getAudioFileWriters() { diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/sampled/DataLine.java --- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/DataLine.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/DataLine.java Tue Aug 19 10:32:16 2014 -0700 @@ -355,11 +355,11 @@ * {@code true} for all formats returned by {@code getFormats()}. *

* Some fields in the AudioFormat instances can be set to - * {@link javax.sound.sampled.AudioSystem#NOT_SPECIFIED NOT_SPECIFIED} - * if that field does not apply to the format, or if the format supports - * a wide range of values for that field. For example, a multi-channel - * device supporting up to 64 channels, could set the channel field in - * the {@code AudioFormat} instances returned by this method to + * {@link AudioSystem#NOT_SPECIFIED NOT_SPECIFIED} if that field does + * not apply to the format, or if the format supports a wide range of + * values for that field. For example, a multi-channel device supporting + * up to 64 channels, could set the channel field in the + * {@code AudioFormat} instances returned by this method to * {@code NOT_SPECIFIED}. * * @return a set of supported audio formats diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/sampled/spi/AudioFileReader.java --- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/spi/AudioFileReader.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/spi/AudioFileReader.java Tue Aug 19 10:32:16 2014 -0700 @@ -26,8 +26,8 @@ package javax.sound.sampled.spi; import java.io.File; +import java.io.IOException; import java.io.InputStream; -import java.io.IOException; import java.net.URL; import javax.sound.sampled.AudioFileFormat; diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/sound/sampled/spi/AudioFileWriter.java --- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/spi/AudioFileWriter.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/spi/AudioFileWriter.java Tue Aug 19 10:32:16 2014 -0700 @@ -30,6 +30,7 @@ import java.io.OutputStream; import javax.sound.sampled.AudioInputStream; +import javax.sound.sampled.AudioSystem; import static javax.sound.sampled.AudioFileFormat.Type; @@ -110,8 +111,7 @@ * the length be written into the file header, and cannot be written from * start to finish unless the length is known in advance. An attempt to * write such a file type will fail with an IOException if the length in the - * audio file format is {@link javax.sound.sampled.AudioSystem#NOT_SPECIFIED - * AudioSystem.NOT_SPECIFIED}. + * audio file format is {@link AudioSystem#NOT_SPECIFIED}. * * @param stream the audio input stream containing audio data to be written * to the output stream diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/CellEditor.java --- a/jdk/src/java.desktop/share/classes/javax/swing/CellEditor.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/CellEditor.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 2005, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -47,7 +47,7 @@ * new component implement the interface. Or the developer can * choose a wrapper based approach and provide a companion object which * implements the CellEditor interface (See - * JCellEditor for example). The wrapper approach + * DefaultCellEditor for example). The wrapper approach * is particularly useful if the user want to use a 3rd party ISV * editor with JTable, but the ISV didn't implement the * CellEditor interface. The user can simply create an object diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/ImageIcon.java --- a/jdk/src/java.desktop/share/classes/javax/swing/ImageIcon.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/ImageIcon.java Tue Aug 19 10:32:16 2014 -0700 @@ -490,12 +490,33 @@ private void readObject(ObjectInputStream s) throws ClassNotFoundException, IOException { - s.defaultReadObject(); + ObjectInputStream.GetField f = s.readFields(); + + imageObserver = (ImageObserver) f.get("imageObserver", null); + description = (String) f.get("description", null); + width = f.get("width", -1); + height = f.get("height", -1); + accessibleContext = (AccessibleImageIcon) f.get("accessibleContext", null); int w = s.readInt(); int h = s.readInt(); int[] pixels = (int[])(s.readObject()); + if (pixels == null && (w != -1 || h != -1)) { + throw new IllegalStateException("Inconsistent width and height" + + " for null image [" + w + ", " + h + "]"); + } + + if (pixels != null && (w < 0 || h < 0)) { + throw new IllegalStateException("Inconsistent width and height" + + " for image [" + w + ", " + h + "]"); + } + + if (w != getIconWidth() || h != getIconHeight()) { + throw new IllegalStateException("Inconsistent width and height" + + " for image [" + w + ", " + h + "]"); + } + if (pixels != null) { Toolkit tk = Toolkit.getDefaultToolkit(); ColorModel cm = ColorModel.getRGBdefault(); diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/JComponent.java --- a/jdk/src/java.desktop/share/classes/javax/swing/JComponent.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/JComponent.java Tue Aug 19 10:32:16 2014 -0700 @@ -1888,7 +1888,7 @@ * description: The preferred vertical alignment of the component. */ public void setAlignmentY(float alignmentY) { - this.alignmentY = alignmentY > 1.0f ? 1.0f : alignmentY < 0.0f ? 0.0f : alignmentY; + this.alignmentY = validateAlignment(alignmentY); isAlignmentYSet = true; } @@ -1917,10 +1917,14 @@ * description: The preferred horizontal alignment of the component. */ public void setAlignmentX(float alignmentX) { - this.alignmentX = alignmentX > 1.0f ? 1.0f : alignmentX < 0.0f ? 0.0f : alignmentX; + this.alignmentX = validateAlignment(alignmentX); isAlignmentXSet = true; } + private float validateAlignment(float alignment) { + return alignment > 1.0f ? 1.0f : alignment < 0.0f ? 0.0f : alignment; + } + /** * Sets the input verifier for this component. * @@ -5514,7 +5518,24 @@ private void readObject(ObjectInputStream s) throws IOException, ClassNotFoundException { - s.defaultReadObject(); + ObjectInputStream.GetField f = s.readFields(); + + isAlignmentXSet = f.get("isAlignmentXSet", false); + alignmentX = validateAlignment(f.get("alignmentX", 0f)); + isAlignmentYSet = f.get("isAlignmentYSet", false); + alignmentY = validateAlignment(f.get("alignmentY", 0f)); + listenerList = (EventListenerList) f.get("listenerList", null); + vetoableChangeSupport = (VetoableChangeSupport) f.get("vetoableChangeSupport", null); + autoscrolls = f.get("autoscrolls", false); + border = (Border) f.get("border", null); + flags = f.get("flags", 0); + inputVerifier = (InputVerifier) f.get("inputVerifier", null); + verifyInputWhenFocusTarget = f.get("verifyInputWhenFocusTarget", false); + popupMenu = (JPopupMenu) f.get("popupMenu", null); + focusInputMap = (InputMap) f.get("focusInputMap", null); + ancestorInputMap = (InputMap) f.get("ancestorInputMap", null); + windowInputMap = (ComponentInputMap) f.get("windowInputMap", null); + actionMap = (ActionMap) f.get("actionMap", null); /* If there's no ReadObjectCallback for this stream yet, that is, if * this is the first call to JComponent.readObject() for this diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/JFileChooser.java --- a/jdk/src/java.desktop/share/classes/javax/swing/JFileChooser.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/JFileChooser.java Tue Aug 19 10:32:16 2014 -0700 @@ -50,6 +50,8 @@ import java.awt.event.*; import java.beans.PropertyChangeListener; import java.beans.PropertyChangeEvent; +import java.io.InvalidObjectException; +import java.io.ObjectInputStream; import java.lang.ref.WeakReference; /** @@ -460,10 +462,14 @@ * bound: false */ public void setDragEnabled(boolean b) { + checkDragEnabled(b); + dragEnabled = b; + } + + private static void checkDragEnabled(boolean b) { if (b && GraphicsEnvironment.isHeadless()) { throw new HeadlessException(); } - dragEnabled = b; } /** @@ -949,9 +955,7 @@ if(this.dialogType == dialogType) { return; } - if(!(dialogType == OPEN_DIALOG || dialogType == SAVE_DIALOG || dialogType == CUSTOM_DIALOG)) { - throw new IllegalArgumentException("Incorrect Dialog Type: " + dialogType); - } + checkDialogType(dialogType); int oldValue = this.dialogType; this.dialogType = dialogType; if(dialogType == OPEN_DIALOG || dialogType == SAVE_DIALOG) { @@ -960,6 +964,14 @@ firePropertyChange(DIALOG_TYPE_CHANGED_PROPERTY, oldValue, dialogType); } + private static void checkDialogType(int dialogType) { + if (!(dialogType == OPEN_DIALOG || dialogType == SAVE_DIALOG + || dialogType == CUSTOM_DIALOG)) { + throw new IllegalArgumentException( + "Incorrect Dialog Type: " + dialogType); + } + } + /** * Sets the string that goes in the JFileChooser window's * title bar. @@ -1349,12 +1361,17 @@ return; } - if ((mode == FILES_ONLY) || (mode == DIRECTORIES_ONLY) || (mode == FILES_AND_DIRECTORIES)) { + checkFileSelectionMode(mode); int oldValue = fileSelectionMode; fileSelectionMode = mode; firePropertyChange(FILE_SELECTION_MODE_CHANGED_PROPERTY, oldValue, fileSelectionMode); - } else { - throw new IllegalArgumentException("Incorrect Mode for file selection: " + mode); + } + + private static void checkFileSelectionMode(int mode) { + if ((mode != FILES_ONLY) && (mode != DIRECTORIES_ONLY) + && (mode != FILES_AND_DIRECTORIES)) { + throw new IllegalArgumentException( + "Incorrect Mode for file selection: " + mode); } } @@ -1901,7 +1918,43 @@ */ private void readObject(java.io.ObjectInputStream in) throws IOException, ClassNotFoundException { - in.defaultReadObject(); + ObjectInputStream.GetField f = in.readFields(); + + dialogTitle = (String) f.get("dialogTitle", null); + approveButtonText = (String) f.get("approveButtonText", null); + approveButtonToolTipText = + (String) f.get("approveButtonToolTipText", null); + approveButtonMnemonic = f.get("approveButtonMnemonic", 0); + @SuppressWarnings("unchecked") + Vector newFilters = (Vector) f.get("filters", null); + if (newFilters == null) { + throw new InvalidObjectException("Null filters"); + } + filters = newFilters; + dialog = (JDialog) f.get("dialog", null); + int newDialogType = f.get("dialogType", OPEN_DIALOG); + checkDialogType(newDialogType); + dialogType = newDialogType; + returnValue = f.get("returnValue", 0); + accessory = (JComponent) f.get("accessory", null); + fileView = (FileView) f.get("fileView", null); + controlsShown = f.get("controlsShown", false); + useFileHiding = f.get("useFileHiding", false); + int newFileSelectionMode = f.get("fileSelectionMode", FILES_ONLY); + checkFileSelectionMode(newFileSelectionMode); + fileSelectionMode = newFileSelectionMode; + multiSelectionEnabled = f.get("multiSelectionEnabled", false); + useAcceptAllFileFilter = f.get("useAcceptAllFileFilter", false); + boolean newDragEnabled = f.get("dragEnabled", false); + checkDragEnabled(newDragEnabled); + dragEnabled = newDragEnabled; + fileFilter = (FileFilter) f.get("fileFilter", null); + fileSystemView = (FileSystemView) f.get("fileSystemView", null); + currentDirectory = (File) f.get("currentDirectory", null); + selectedFile = (File) f.get("selectedFile", null); + selectedFiles = (File[]) f.get("selectedFiles", null); + accessibleContext = (AccessibleContext) f.get("accessibleContext", null); + installShowFilesListener(); } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/JFrame.java --- a/jdk/src/java.desktop/share/classes/javax/swing/JFrame.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/JFrame.java Tue Aug 19 10:32:16 2014 -0700 @@ -24,14 +24,22 @@ */ package javax.swing; -import java.awt.*; -import java.awt.event.*; -import java.beans.PropertyChangeListener; -import java.util.Locale; -import java.util.Vector; -import java.io.Serializable; +import java.awt.AWTEvent; +import java.awt.BorderLayout; +import java.awt.Component; +import java.awt.Container; +import java.awt.Frame; +import java.awt.Graphics; +import java.awt.GraphicsConfiguration; +import java.awt.HeadlessException; +import java.awt.Image; +import java.awt.LayoutManager; +import java.awt.event.WindowEvent; -import javax.accessibility.*; +import javax.accessibility.Accessible; +import javax.accessibility.AccessibleContext; +import javax.accessibility.AccessibleState; +import javax.accessibility.AccessibleStateSet; /** @@ -297,33 +305,28 @@ * @see #setDefaultCloseOperation * @see java.awt.Window#processWindowEvent */ - protected void processWindowEvent(WindowEvent e) { + protected void processWindowEvent(final WindowEvent e) { super.processWindowEvent(e); if (e.getID() == WindowEvent.WINDOW_CLOSING) { - switch(defaultCloseOperation) { - case HIDE_ON_CLOSE: - setVisible(false); - break; - case DISPOSE_ON_CLOSE: - dispose(); - break; - case DO_NOTHING_ON_CLOSE: - default: - break; - case EXIT_ON_CLOSE: - // This needs to match the checkExit call in - // setDefaultCloseOperation - System.exit(0); - break; + switch (defaultCloseOperation) { + case HIDE_ON_CLOSE: + setVisible(false); + break; + case DISPOSE_ON_CLOSE: + dispose(); + break; + case EXIT_ON_CLOSE: + // This needs to match the checkExit call in + // setDefaultCloseOperation + System.exit(0); + break; + case DO_NOTHING_ON_CLOSE: + default: } } } -// public void setMenuBar(MenuBar menu) { -// throw new IllegalComponentStateException("Please use setJMenuBar() with JFrame."); -// } - /** * Sets the operation that will happen by default when * the user initiates a "close" on this frame. diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/JLayer.java --- a/jdk/src/java.desktop/share/classes/javax/swing/JLayer.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/JLayer.java Tue Aug 19 10:32:16 2014 -0700 @@ -158,8 +158,9 @@ private LayerUI layerUI; private JPanel glassPane; private long eventMask; - private transient boolean isPainting; - private transient boolean isPaintingImmediately; + private transient boolean isPaintCalling; + private transient boolean isPaintImmediatelyCalling; + private transient boolean isImageUpdateCalling; private static final LayerEventController eventController = new LayerEventController(); @@ -405,12 +406,12 @@ * @param h the height of the region to be painted */ public void paintImmediately(int x, int y, int w, int h) { - if (!isPaintingImmediately && getUI() != null) { - isPaintingImmediately = true; + if (!isPaintImmediatelyCalling && getUI() != null) { + isPaintImmediatelyCalling = true; try { getUI().paintImmediately(x, y, w, h, this); } finally { - isPaintingImmediately = false; + isPaintImmediatelyCalling = false; } } else { super.paintImmediately(x, y, w, h); @@ -418,17 +419,44 @@ } /** + * Delegates its functionality to the + * {@link javax.swing.plaf.LayerUI#imageUpdate(java.awt.Image, int, int, int, int, int, JLayer)} method, + * if the {@code LayerUI} is set. + * + * @param img the image being observed + * @param infoflags see {@code imageUpdate} for more information + * @param x the x coordinate + * @param y the y coordinate + * @param w the width + * @param h the height + * @return {@code false} if the infoflags indicate that the + * image is completely loaded; {@code true} otherwise. + */ + public boolean imageUpdate(Image img, int infoflags, int x, int y, int w, int h) { + if (!isImageUpdateCalling && getUI() != null) { + isImageUpdateCalling = true; + try { + return getUI().imageUpdate(img, infoflags, x, y, w, h, this); + } finally { + isImageUpdateCalling = false; + } + } else { + return super.imageUpdate(img, infoflags, x, y, w, h); + } + } + + /** * Delegates all painting to the {@link javax.swing.plaf.LayerUI} object. * * @param g the {@code Graphics} to render to */ public void paint(Graphics g) { - if (!isPainting) { - isPainting = true; + if (!isPaintCalling) { + isPaintCalling = true; try { super.paintComponent(g); } finally { - isPainting = false; + isPaintCalling = false; } } else { super.paint(g); @@ -646,15 +674,21 @@ return 1; } + @SuppressWarnings("unchecked") private void readObject(ObjectInputStream s) throws IOException, ClassNotFoundException { - s.defaultReadObject(); - if (layerUI != null) { - setUI(layerUI); - } + ObjectInputStream.GetField f = s.readFields(); + + view = (V) f.get("view", null); + glassPane = (JPanel) f.get("glassPane", null); + eventMask = f.get("eventMask", 0l); if (eventMask != 0) { eventController.updateAWTEventListener(0, eventMask); } + LayerUI newLayerUI = (LayerUI) f.get("layerUI", null); + if (newLayerUI != null) { + setUI(newLayerUI); + } } /** diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/JOptionPane.java --- a/jdk/src/java.desktop/share/classes/javax/swing/JOptionPane.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/JOptionPane.java Tue Aug 19 10:32:16 2014 -0700 @@ -43,13 +43,10 @@ import java.awt.event.ComponentAdapter; import java.awt.event.ComponentEvent; import java.io.IOException; +import java.io.InvalidObjectException; import java.io.ObjectInputStream; import java.io.ObjectOutputStream; import java.io.Serializable; -import java.lang.reflect.Method; -import java.lang.reflect.InvocationTargetException; -import java.security.AccessController; -import java.security.PrivilegedAction; import java.util.Vector; import javax.swing.plaf.OptionPaneUI; import javax.swing.event.InternalFrameEvent; @@ -2055,15 +2052,22 @@ * description: The option pane's message type. */ public void setMessageType(int newType) { + checkMessageType(newType); + int oldType = messageType; + messageType = newType; + firePropertyChange(MESSAGE_TYPE_PROPERTY, oldType, messageType); + } + + private static void checkMessageType(int newType){ if(newType != ERROR_MESSAGE && newType != INFORMATION_MESSAGE && newType != WARNING_MESSAGE && newType != QUESTION_MESSAGE && newType != PLAIN_MESSAGE) - throw new RuntimeException("JOptionPane: type must be one of JOptionPane.ERROR_MESSAGE, JOptionPane.INFORMATION_MESSAGE, JOptionPane.WARNING_MESSAGE, JOptionPane.QUESTION_MESSAGE or JOptionPane.PLAIN_MESSAGE"); - - int oldType = messageType; - - messageType = newType; - firePropertyChange(MESSAGE_TYPE_PROPERTY, oldType, messageType); + throw new RuntimeException("JOptionPane: type must be one of" + + " JOptionPane.ERROR_MESSAGE," + + " JOptionPane.INFORMATION_MESSAGE," + + " JOptionPane.WARNING_MESSAGE," + + " JOptionPane.QUESTION_MESSAGE" + + " or JOptionPane.PLAIN_MESSAGE"); } /** @@ -2097,16 +2101,23 @@ * description: The option pane's option type. */ public void setOptionType(int newType) { - if(newType != DEFAULT_OPTION && newType != YES_NO_OPTION && - newType != YES_NO_CANCEL_OPTION && newType != OK_CANCEL_OPTION) - throw new RuntimeException("JOptionPane: option type must be one of JOptionPane.DEFAULT_OPTION, JOptionPane.YES_NO_OPTION, JOptionPane.YES_NO_CANCEL_OPTION or JOptionPane.OK_CANCEL_OPTION"); - + checkOptionType(newType); int oldType = optionType; - optionType = newType; firePropertyChange(OPTION_TYPE_PROPERTY, oldType, optionType); } + private static void checkOptionType(int newType) { + if (newType != DEFAULT_OPTION && newType != YES_NO_OPTION + && newType != YES_NO_CANCEL_OPTION + && newType != OK_CANCEL_OPTION) { + throw new RuntimeException("JOptionPane: option type must be one of" + + " JOptionPane.DEFAULT_OPTION, JOptionPane.YES_NO_OPTION," + + " JOptionPane.YES_NO_CANCEL_OPTION" + + " or JOptionPane.OK_CANCEL_OPTION"); + } + } + /** * Returns the type of options that are displayed. * @@ -2385,7 +2396,15 @@ private void readObject(ObjectInputStream s) throws IOException, ClassNotFoundException { - s.defaultReadObject(); + ObjectInputStream.GetField f = s.readFields(); + + int newMessageType = f.get("messageType", 0); + checkMessageType(newMessageType); + messageType = newMessageType; + int newOptionType = f.get("optionType", 0); + checkOptionType(newOptionType); + optionType = newOptionType; + wantsInput = f.get("wantsInput", false); Vector values = (Vector)s.readObject(); int indexCounter = 0; diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/JPopupMenu.java --- a/jdk/src/java.desktop/share/classes/javax/swing/JPopupMenu.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/JPopupMenu.java Tue Aug 19 10:32:16 2014 -0700 @@ -1345,7 +1345,20 @@ // implements javax.swing.MenuElement private void readObject(ObjectInputStream s) throws IOException, ClassNotFoundException { - s.defaultReadObject(); + ObjectInputStream.GetField f = s.readFields(); + + int newDesiredLocationX = f.get("desiredLocationX", 0); + int newDesiredLocationY = f.get("desiredLocationY", 0); + Point p = adjustPopupLocationToFitScreen( + newDesiredLocationX, newDesiredLocationY); + desiredLocationX = p.x; + desiredLocationY = p.y; + + label = (String) f.get("label", null); + paintBorder = f.get("paintBorder", false); + margin = (Insets) f.get("margin", null); + lightWeightPopup = f.get("lightWeightPopup", false); + selectionModel = (SingleSelectionModel) f.get("selectionModel", null); Vector values = (Vector)s.readObject(); int indexCounter = 0; diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/JTabbedPane.java --- a/jdk/src/java.desktop/share/classes/javax/swing/JTabbedPane.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/JTabbedPane.java Tue Aug 19 10:32:16 2014 -0700 @@ -495,10 +495,7 @@ * */ public void setTabPlacement(int tabPlacement) { - if (tabPlacement != TOP && tabPlacement != LEFT && - tabPlacement != BOTTOM && tabPlacement != RIGHT) { - throw new IllegalArgumentException("illegal tab placement: must be TOP, BOTTOM, LEFT, or RIGHT"); - } + checkTabPlacement(tabPlacement); if (this.tabPlacement != tabPlacement) { int oldValue = this.tabPlacement; this.tabPlacement = tabPlacement; @@ -508,6 +505,14 @@ } } + private static void checkTabPlacement(int tabPlacement) { + if (tabPlacement != TOP && tabPlacement != LEFT && + tabPlacement != BOTTOM && tabPlacement != RIGHT) { + throw new IllegalArgumentException("illegal tab placement:" + + " must be TOP, BOTTOM, LEFT, or RIGHT"); + } + } + /** * Returns the policy used by the tabbedpane to layout the tabs when all the * tabs will not fit within a single run. @@ -551,9 +556,7 @@ * */ public void setTabLayoutPolicy(int tabLayoutPolicy) { - if (tabLayoutPolicy != WRAP_TAB_LAYOUT && tabLayoutPolicy != SCROLL_TAB_LAYOUT) { - throw new IllegalArgumentException("illegal tab layout policy: must be WRAP_TAB_LAYOUT or SCROLL_TAB_LAYOUT"); - } + checkTabLayoutPolicy(tabLayoutPolicy); if (this.tabLayoutPolicy != tabLayoutPolicy) { int oldValue = this.tabLayoutPolicy; this.tabLayoutPolicy = tabLayoutPolicy; @@ -563,6 +566,14 @@ } } + private static void checkTabLayoutPolicy(int tabLayoutPolicy) { + if (tabLayoutPolicy != WRAP_TAB_LAYOUT + && tabLayoutPolicy != SCROLL_TAB_LAYOUT) { + throw new IllegalArgumentException("illegal tab layout policy:" + + " must be WRAP_TAB_LAYOUT or SCROLL_TAB_LAYOUT"); + } + } + /** * Returns the currently selected index for this tabbedpane. * Returns -1 if there is no currently selected tab. @@ -1816,7 +1827,19 @@ private void readObject(ObjectInputStream s) throws IOException, ClassNotFoundException { - s.defaultReadObject(); + ObjectInputStream.GetField f = s.readFields(); + + int newTabPlacement = f.get("tabPlacement", TOP); + checkTabPlacement(newTabPlacement); + tabPlacement = newTabPlacement; + int newTabLayoutPolicy = f.get("tabLayoutPolicy", 0); + checkTabLayoutPolicy(newTabLayoutPolicy); + tabLayoutPolicy = newTabLayoutPolicy; + model = (SingleSelectionModel) f.get("model", null); + haveRegistered = f.get("haveRegistered", false); + changeListener = (ChangeListener) f.get("changeListener", null); + visComp = (Component) f.get("visComp", null); + if ((ui != null) && (getUIClassID().equals(uiClassID))) { ui.installUI(this); } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/JTable.java --- a/jdk/src/java.desktop/share/classes/javax/swing/JTable.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/JTable.java Tue Aug 19 10:32:16 2014 -0700 @@ -37,6 +37,7 @@ import java.io.ObjectOutputStream; import java.io.ObjectInputStream; import java.io.IOException; +import java.io.InvalidObjectException; import javax.accessibility.*; @@ -1203,11 +1204,7 @@ * AUTO_RESIZE_ALL_COLUMNS JTable.AUTO_RESIZE_ALL_COLUMNS */ public void setAutoResizeMode(int mode) { - if ((mode == AUTO_RESIZE_OFF) || - (mode == AUTO_RESIZE_NEXT_COLUMN) || - (mode == AUTO_RESIZE_SUBSEQUENT_COLUMNS) || - (mode == AUTO_RESIZE_LAST_COLUMN) || - (mode == AUTO_RESIZE_ALL_COLUMNS)) { + if (isValidAutoResizeMode(mode)) { int old = autoResizeMode; autoResizeMode = mode; resizeAndRepaint(); @@ -1218,6 +1215,14 @@ } } + private static boolean isValidAutoResizeMode(int mode) { + return (mode == AUTO_RESIZE_OFF) + || (mode == AUTO_RESIZE_NEXT_COLUMN) + || (mode == AUTO_RESIZE_SUBSEQUENT_COLUMNS) + || (mode == AUTO_RESIZE_LAST_COLUMN) + || (mode == AUTO_RESIZE_ALL_COLUMNS); + } + /** * Returns the auto resize mode of the table. The default mode * is AUTO_RESIZE_SUBSEQUENT_COLUMNS. @@ -1439,10 +1444,14 @@ * bound: false */ public void setDragEnabled(boolean b) { + checkDragEnabled(b); + dragEnabled = b; + } + + private void checkDragEnabled(boolean b) { if (b && GraphicsEnvironment.isHeadless()) { throw new HeadlessException(); } - dragEnabled = b; } /** @@ -1489,6 +1498,11 @@ * @since 1.6 */ public final void setDropMode(DropMode dropMode) { + checkDropMode(dropMode); + this.dropMode = dropMode; + } + + private static void checkDropMode(DropMode dropMode) { if (dropMode != null) { switch (dropMode) { case USE_SELECTION: @@ -1499,14 +1513,12 @@ case ON_OR_INSERT: case ON_OR_INSERT_ROWS: case ON_OR_INSERT_COLS: - this.dropMode = dropMode; return; } } - - throw new IllegalArgumentException(dropMode + ": Unsupported drop mode for table"); - } - + throw new IllegalArgumentException(dropMode + + ": Unsupported drop mode for table"); + } /** * Returns the drop mode for this component. * @@ -5865,7 +5877,75 @@ private void readObject(ObjectInputStream s) throws IOException, ClassNotFoundException { - s.defaultReadObject(); + ObjectInputStream.GetField f = s.readFields(); + + TableModel newDataModel = (TableModel) f.get("dataModel", null); + if (newDataModel == null) { + throw new InvalidObjectException("Null dataModel"); + } + dataModel = newDataModel; + + TableColumnModel newColumnModel = (TableColumnModel) f.get("columnModel", null); + if (newColumnModel == null) { + throw new InvalidObjectException("Null columnModel"); + } + columnModel = newColumnModel; + + ListSelectionModel newSelectionModel = (ListSelectionModel) f.get("selectionModel", null); + if (newSelectionModel == null) { + throw new InvalidObjectException("Null selectionModel"); + } + selectionModel = newSelectionModel; + + tableHeader = (JTableHeader) f.get("tableHeader", null); + int newRowHeight = f.get("rowHeight", 0); + if (newRowHeight <= 0) { + throw new InvalidObjectException("Row height less than 1"); + } + rowHeight = newRowHeight; + + rowMargin = f.get("rowMargin", 0); + Color newGridColor = (Color) f.get("gridColor", null); + if (newGridColor == null) { + throw new InvalidObjectException("Null gridColor"); + } + gridColor = newGridColor; + + showHorizontalLines = f.get("showHorizontalLines", false); + showVerticalLines = f.get("showVerticalLines", false); + int newAutoResizeMode = f.get("autoResizeMode", 0); + if (!isValidAutoResizeMode(newAutoResizeMode)) { + throw new InvalidObjectException("autoResizeMode is not valid"); + } + autoResizeMode = newAutoResizeMode; + autoCreateColumnsFromModel = f.get("autoCreateColumnsFromModel", false); + preferredViewportSize = (Dimension) f.get("preferredViewportSize", null); + rowSelectionAllowed = f.get("rowSelectionAllowed", false); + cellSelectionEnabled = f.get("cellSelectionEnabled", false); + selectionForeground = (Color) f.get("selectionForeground", null); + selectionBackground = (Color) f.get("selectionBackground", null); + rowModel = (SizeSequence) f.get("rowModel", null); + + boolean newDragEnabled = f.get("dragEnabled", false); + checkDragEnabled(newDragEnabled); + dragEnabled = newDragEnabled; + + surrendersFocusOnKeystroke = f.get("surrendersFocusOnKeystroke", false); + editorRemover = (PropertyChangeListener) f.get("editorRemover", null); + columnSelectionAdjusting = f.get("columnSelectionAdjusting", false); + rowSelectionAdjusting = f.get("rowSelectionAdjusting", false); + printError = (Throwable) f.get("printError", null); + isRowHeightSet = f.get("isRowHeightSet", false); + updateSelectionOnSort = f.get("updateSelectionOnSort", false); + ignoreSortChange = f.get("ignoreSortChange", false); + sorterChanged = f.get("sorterChanged", false); + autoCreateRowSorter = f.get("autoCreateRowSorter", false); + fillsViewportHeight = f.get("fillsViewportHeight", false); + DropMode newDropMode = (DropMode) f.get("dropMode", + DropMode.USE_SELECTION); + checkDropMode(newDropMode); + dropMode = newDropMode; + if ((ui != null) && (getUIClassID().equals(uiClassID))) { ui.installUI(this); } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/JTree.java --- a/jdk/src/java.desktop/share/classes/javax/swing/JTree.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/JTree.java Tue Aug 19 10:32:16 2014 -0700 @@ -1216,10 +1216,14 @@ * bound: false */ public void setDragEnabled(boolean b) { + checkDragEnabled(b); + dragEnabled = b; + } + + private static void checkDragEnabled(boolean b) { if (b && GraphicsEnvironment.isHeadless()) { throw new HeadlessException(); } - dragEnabled = b; } /** @@ -1262,18 +1266,23 @@ * @since 1.6 */ public final void setDropMode(DropMode dropMode) { + checkDropMode(dropMode); + this.dropMode = dropMode; + } + + private static void checkDropMode(DropMode dropMode) { if (dropMode != null) { switch (dropMode) { case USE_SELECTION: case ON: case INSERT: case ON_OR_INSERT: - this.dropMode = dropMode; return; } } - throw new IllegalArgumentException(dropMode + ": Unsupported drop mode for tree"); + throw new IllegalArgumentException(dropMode + + ": Unsupported drop mode for tree"); } /** @@ -3089,7 +3098,34 @@ private void readObject(ObjectInputStream s) throws IOException, ClassNotFoundException { - s.defaultReadObject(); + ObjectInputStream.GetField f = s.readFields(); + + rootVisible = f.get("rootVisible", false); + rowHeight = f.get("rowHeight", 0); + rowHeightSet = f.get("rowHeightSet", false); + showsRootHandles = f.get("showsRootHandles", false); + showsRootHandlesSet = f.get("showsRootHandlesSet", false); + editable = f.get("editable", false); + largeModel = f.get("largeModel", false); + visibleRowCount = f.get("visibleRowCount", 0); + invokesStopCellEditing = f.get("invokesStopCellEditing", false); + scrollsOnExpand = f.get("scrollsOnExpand", false); + scrollsOnExpandSet = f.get("scrollsOnExpandSet", false); + toggleClickCount = f.get("toggleClickCount", 0); + leadPath = (TreePath) f.get("leadPath", null); + anchorPath = (TreePath) f.get("anchorPath", null); + expandsSelectedPaths = f.get("expandsSelectedPaths", false); + settingUI = f.get("settingUI", false); + boolean newDragEnabled = f.get("dragEnabled", false); + checkDragEnabled(newDragEnabled); + dragEnabled = newDragEnabled; + DropMode newDropMode = (DropMode) f.get("dropMode", + DropMode.USE_SELECTION); + checkDropMode(newDropMode); + dropMode = newDropMode; + + expandRow = f.get("expandRow", -1); + dropTimer = (TreeTimer) f.get("dropTimer", null); // Create an instance of expanded state. diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/LegacyGlueFocusTraversalPolicy.java --- a/jdk/src/java.desktop/share/classes/javax/swing/LegacyGlueFocusTraversalPolicy.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/LegacyGlueFocusTraversalPolicy.java Tue Aug 19 10:32:16 2014 -0700 @@ -194,7 +194,23 @@ private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException { - in.defaultReadObject(); + ObjectInputStream.GetField f = in.readFields(); + + @SuppressWarnings("unchecked") + HashMap newForwardMap = + (HashMap ) f.get("forwardMap", null); + if (newForwardMap == null) { + throw new InvalidObjectException("Null forwardMap"); + } + forwardMap = newForwardMap; + @SuppressWarnings("unchecked") + HashMap newBackwardMap = + (HashMap) f.get("backwardMap", null); + if (newBackwardMap == null) { + throw new InvalidObjectException("Null backwardMap"); + } + backwardMap = newBackwardMap; + delegatePolicy = (FocusTraversalPolicy)in.readObject(); delegateManager = (DefaultFocusManager)in.readObject(); } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/SwingUtilities.java --- a/jdk/src/java.desktop/share/classes/javax/swing/SwingUtilities.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/SwingUtilities.java Tue Aug 19 10:32:16 2014 -0700 @@ -374,7 +374,8 @@ sourceWheelEvent.isPopupTrigger(), sourceWheelEvent.getScrollType(), sourceWheelEvent.getScrollAmount(), - sourceWheelEvent.getWheelRotation()); + sourceWheelEvent.getWheelRotation(), + sourceWheelEvent.getPreciseWheelRotation()); } else if (sourceEvent instanceof MenuDragMouseEvent) { MenuDragMouseEvent sourceMenuDragEvent = (MenuDragMouseEvent)sourceEvent; diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/Timer.java --- a/jdk/src/java.desktop/share/classes/javax/swing/Timer.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/Timer.java Tue Aug 19 10:32:16 2014 -0700 @@ -401,14 +401,15 @@ * @see #setInitialDelay */ public void setDelay(int delay) { - if (delay < 0) { - throw new IllegalArgumentException("Invalid delay: " + delay); - } - else { + checkDelay(delay, "Invalid delay: "); this.delay = delay; } + + private static void checkDelay(int delay, String message) { + if (delay < 0) { + throw new IllegalArgumentException(message + delay); } - + } /** * Returns the delay, in milliseconds, @@ -435,14 +436,9 @@ * @see #setDelay */ public void setInitialDelay(int initialDelay) { - if (initialDelay < 0) { - throw new IllegalArgumentException("Invalid initial delay: " + - initialDelay); - } - else { + checkDelay(initialDelay, "Invalid initial delay: "); this.initialDelay = initialDelay; } - } /** @@ -638,7 +634,26 @@ throws ClassNotFoundException, IOException { this.acc = AccessController.getContext(); - in.defaultReadObject(); + ObjectInputStream.GetField f = in.readFields(); + + EventListenerList newListenerList = (EventListenerList) + f.get("listenerList", null); + if (newListenerList == null) { + throw new InvalidObjectException("Null listenerList"); + } + listenerList = newListenerList; + + int newInitialDelay = f.get("initialDelay", 0); + checkDelay(newInitialDelay, "Invalid initial delay: "); + initialDelay = newInitialDelay; + + int newDelay = f.get("delay", 0); + checkDelay(newDelay, "Invalid delay: "); + delay = newDelay; + + repeats = f.get("repeats", false); + coalesce = f.get("coalesce", false); + actionCommand = (String) f.get("actionCommand", null); } /* diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/event/SwingPropertyChangeSupport.java --- a/jdk/src/java.desktop/share/classes/javax/swing/event/SwingPropertyChangeSupport.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/event/SwingPropertyChangeSupport.java Tue Aug 19 10:32:16 2014 -0700 @@ -107,7 +107,7 @@ * @see #SwingPropertyChangeSupport(Object sourceBean, boolean notifyOnEDT) * @since 1.6 */ - public final boolean isNotifyOnEDT() { + public boolean isNotifyOnEDT() { return notifyOnEDT; } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/plaf/ComboBoxUI.java --- a/jdk/src/java.desktop/share/classes/javax/swing/plaf/ComboBoxUI.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/plaf/ComboBoxUI.java Tue Aug 19 10:32:16 2014 -0700 @@ -37,16 +37,25 @@ /** * Set the visibility of the popup + * + * @param c a {@code JComboBox} + * @param v a {@code boolean} determining the visibilty of the popup */ public abstract void setPopupVisible( JComboBox c, boolean v ); /** * Determine the visibility of the popup + * + * @param c a {@code JComboBox} + * @return true if popup of the {@code JComboBox} is visible */ public abstract boolean isPopupVisible( JComboBox c ); /** * Determine whether or not the combo box itself is traversable + * + * @param c a {@code JComboBox} + * @return true if the given {@code JComboBox} is traversable */ public abstract boolean isFocusTraversable( JComboBox c ); } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/plaf/ComponentUI.java --- a/jdk/src/java.desktop/share/classes/javax/swing/plaf/ComponentUI.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/plaf/ComponentUI.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -173,7 +173,8 @@ * this argument is often ignored, * but might be used if the UI object is stateless * and shared by multiple components - * + * @return a {@code Dimension} object containing given component's preferred + * size appropriate for the look and feel * @see javax.swing.JComponent#getPreferredSize * @see java.awt.LayoutManager#preferredLayoutSize */ @@ -240,7 +241,8 @@ * and shared by multiple components * @param x the x coordinate of the point * @param y the y coordinate of the point - * + * @return {@code true} if the specified {@code x,y} location is contained + * within the look and feel's defined shape for the given component * @see javax.swing.JComponent#contains * @see java.awt.Component#contains */ @@ -258,6 +260,9 @@ * stateful, then it should return a new instance per component. * The default implementation of this method throws an error, as it * should never be invoked. + * + * @param c a {@code JComponent} for which to create a UI delegate + * @return a {@code ComponentUI} object for {@code c} */ public static ComponentUI createUI(JComponent c) { throw new Error("ComponentUI.createUI not implemented."); @@ -332,8 +337,9 @@ * Component.AccessibleAWTComponent.getAccessibleChildrenCount() instead * of this method. * + * @param c {@code JComponent} for which to get count of accessible children + * @return the number of accessible children in the object * @see #getAccessibleChild - * @return the number of accessible children in the object */ public int getAccessibleChildrenCount(JComponent c) { return SwingUtilities.getAccessibleChildrenCount(c); @@ -351,9 +357,10 @@ * Component.AccessibleAWTComponent.getAccessibleChild() instead of * this method. * - * @see #getAccessibleChildrenCount + * @param c a {@code JComponent} for which to get a child object * @param i zero-based index of child * @return the ith Accessible child of the object + * @see #getAccessibleChildrenCount */ public Accessible getAccessibleChild(JComponent c, int i) { return SwingUtilities.getAccessibleChild(c, i); diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/plaf/FileChooserUI.java --- a/jdk/src/java.desktop/share/classes/javax/swing/plaf/FileChooserUI.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/plaf/FileChooserUI.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 2008, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -52,6 +52,8 @@ * JFileChooser will use this button as default button * for dialog windows. * + * @param fc the {@code JFileChooser} whose default button is requested + * @return the default JButton for current look and feel * @since 1.7 */ public JButton getDefaultButton(JFileChooser fc) { diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/plaf/LayerUI.java --- a/jdk/src/java.desktop/share/classes/javax/swing/plaf/LayerUI.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/plaf/LayerUI.java Tue Aug 19 10:32:16 2014 -0700 @@ -716,10 +716,22 @@ * @param y the y value of the region to be painted * @param width the width of the region to be painted * @param height the height of the region to be painted - * + * @param l a {@code JLayer} component * @see JComponent#paintImmediately(int, int, int, int) */ public void paintImmediately(int x, int y, int width, int height, JLayer l) { l.paintImmediately(x, y, width, height); } + + /** + * Delegates its functionality to the default implementation of the {@code JLayer.imageUpdate} method + * which is inherited from {@code JLayer}'s base classes. + *

+ * This method is to be overridden instead of {@code JLayer.imageUpdate}. + *

+ * Note: This method is usually called not on the Event Dispatching Thread. + */ + public boolean imageUpdate(Image img, int infoflags, int x, int y, int w, int h, JLayer l) { + return l.imageUpdate(img, infoflags, x, y, w, h); + } } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/plaf/OptionPaneUI.java --- a/jdk/src/java.desktop/share/classes/javax/swing/plaf/OptionPaneUI.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/plaf/OptionPaneUI.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 1998, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -38,12 +38,18 @@ /** * Requests the component representing the default value to have * focus. + * + * @param op a {@code JOptionPane} */ public abstract void selectInitialValue(JOptionPane op); /** * Returns true if the user has supplied instances of Component for * either the options or message. + * + * @param op a {@code JOptionPane} + * @return {@code true} if the given {@code JOptionPane} contains user + * created {@code Component}s */ public abstract boolean containsCustomComponents(JOptionPane op); } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/plaf/PopupMenuUI.java --- a/jdk/src/java.desktop/share/classes/javax/swing/plaf/PopupMenuUI.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/plaf/PopupMenuUI.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 2000, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -39,6 +39,11 @@ public abstract class PopupMenuUI extends ComponentUI { /** + * Returns whether or not the given {@code MouseEvent} is the popup menu + * trigger event for the platform + * + * @param e a {@code MouseEvent} + * @return true if the {@code MouseEvent e} is the popup menu trigger * @since 1.3 */ public boolean isPopupTrigger(MouseEvent e) { diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/plaf/SplitPaneUI.java --- a/jdk/src/java.desktop/share/classes/javax/swing/plaf/SplitPaneUI.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/plaf/SplitPaneUI.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 1998, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -38,32 +38,49 @@ /** * Messaged to relayout the JSplitPane based on the preferred size * of the children components. + * + * @param jc a {@code JSplitPane} */ public abstract void resetToPreferredSizes(JSplitPane jc); /** * Sets the location of the divider to location. + * + * @param jc a {@code JSplitPane} + * @param location an integer specifying the location of the divider */ public abstract void setDividerLocation(JSplitPane jc, int location); /** * Returns the location of the divider. + * + * @param jc a {@code JSplitPane} + * @return an integer specifying the location of the divider */ public abstract int getDividerLocation(JSplitPane jc); /** * Returns the minimum possible location of the divider. + * + * @param jc a {@code JSplitPane} + * @return and integer specifying the minimum location of the divider */ public abstract int getMinimumDividerLocation(JSplitPane jc); /** * Returns the maximum possible location of the divider. + * + * @param jc a {@code JSplitPane} + * @return an integer specifying the maximum location of the divider */ public abstract int getMaximumDividerLocation(JSplitPane jc); /** * Messaged after the JSplitPane the receiver is providing the look * and feel for paints its children. + * + * @param jc a {@code JSplitPane} + * @param g the {@code Graphics} context */ public abstract void finishedPaintingChildren(JSplitPane jc, Graphics g); } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/plaf/TextUI.java --- a/jdk/src/java.desktop/share/classes/javax/swing/plaf/TextUI.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/plaf/TextUI.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -42,8 +42,9 @@ * Converts the given location in the model to a place in * the view coordinate system. * + * @param t the text component for which this UI is installed * @param pos the local location in the model to translate >= 0 - * @return the coordinates as a rectangle + * @return the coordinates as a {@code Rectangle} * @exception BadLocationException if the given position does not * represent a valid location in the associated document */ @@ -53,8 +54,10 @@ * Converts the given location in the model to a place in * the view coordinate system. * + * @param t the text component for which this UI is installed * @param pos the local location in the model to translate >= 0 - * @return the coordinates as a rectangle + * @param bias the bias for the position + * @return the coordinates as a {@code Rectangle} * @exception BadLocationException if the given position does not * represent a valid location in the associated document */ @@ -64,6 +67,7 @@ * Converts the given place in the view coordinate system * to the nearest representative location in the model. * + * @param t the text component for which this UI is installed * @param pt the location in the view to translate. This * should be in the same coordinate system as the mouse * events. @@ -75,6 +79,7 @@ * Provides a mapping from the view coordinate space to the logical * coordinate space of the model. * + * @param t the text component for which this UI is installed * @param pt the location in the view to translate. * This should be in the same coordinate system * as the mouse events. @@ -117,6 +122,7 @@ * Causes the portion of the view responsible for the * given part of the model to be repainted. * + * @param t the text component for which this UI is installed * @param p0 the beginning of the range >= 0 * @param p1 the end of the range >= p0 */ @@ -126,8 +132,13 @@ * Causes the portion of the view responsible for the * given part of the model to be repainted. * + * @param t the text component for which this UI is installed * @param p0 the beginning of the range >= 0 * @param p1 the end of the range >= p0 + * @param firstBias the bias of the first character position, toward the + * previous character or the next character + * @param secondBias the bias of the second character position, toward the + * previous character or the next character */ public abstract void damageRange(JTextComponent t, int p0, int p1, Position.Bias firstBias, @@ -139,6 +150,7 @@ * things like the commands available, stream readers and * writers, etc. * + * @param t the text component for which this UI is installed * @return the editor kit binding */ public abstract EditorKit getEditorKit(JTextComponent t); @@ -149,13 +161,18 @@ * can be traversed to determine how the model is being * represented spatially. * - * @return the view + * @param t the text component for which this UI is installed + * @return a {@code View} with the allocation of the associated + * text component */ public abstract View getRootView(JTextComponent t); /** * Returns the string to be used as the tooltip at the passed in location. * + * @param t the text component for which this UI is installed + * @param pt a {@code Point} specifying location for which to get a tooltip + * @return a {@code String} containing the tooltip * @see javax.swing.text.JTextComponent#getToolTipText * @since 1.4 */ diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/plaf/TreeUI.java --- a/jdk/src/java.desktop/share/classes/javax/swing/plaf/TreeUI.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/plaf/TreeUI.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 1998, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -38,68 +38,109 @@ public abstract class TreeUI extends ComponentUI { /** - * Returns the Rectangle enclosing the label portion that the - * last item in path will be drawn into. Will return null if - * any component in path is currently valid. - */ + * Returns the Rectangle enclosing the label portion that the + * last item in path will be drawn into. Will return null if + * any component in path is currently valid. + * + * @param tree the {@code JTree} for {@code path} + * @param path the {@code TreePath} identifying the node + * @return the {@code Rectangle} enclosing the label portion that the + * last item in path will be drawn into, {@code null} if any + * component in path is currently valid. + */ public abstract Rectangle getPathBounds(JTree tree, TreePath path); /** - * Returns the path for passed in row. If row is not visible - * null is returned. - */ + * Returns the path for passed in row. If row is not visible + * null is returned. + * + * @param tree a {@code JTree} object + * @param row an integer specifying a row + * @return the {@code path} for {@code row} or {@code null} if {@code row} + * is not visible + */ public abstract TreePath getPathForRow(JTree tree, int row); /** - * Returns the row that the last item identified in path is visible - * at. Will return -1 if any of the elements in path are not - * currently visible. - */ + * Returns the row that the last item identified in path is visible + * at. Will return -1 if any of the elements in path are not + * currently visible. + * + * @param tree the {@code JTree} for {@code path} + * @param path the {@code TreePath} object to look in + * @return an integer specifying the row at which the last item + * identified is visible, -1 if any of the elements in + * {@code path} are not currently visible + */ public abstract int getRowForPath(JTree tree, TreePath path); /** - * Returns the number of rows that are being displayed. - */ + * Returns the number of rows that are being displayed. + * + * @param tree the {@code JTree} for which to count rows + * @return an integer specifying the number of row being displayed + */ public abstract int getRowCount(JTree tree); /** - * Returns the path to the node that is closest to x,y. If - * there is nothing currently visible this will return null, otherwise - * it'll always return a valid path. If you need to test if the - * returned object is exactly at x, y you should get the bounds for - * the returned path and test x, y against that. - */ + * Returns the path to the node that is closest to x,y. If + * there is nothing currently visible this will return null, otherwise + * it'll always return a valid path. If you need to test if the + * returned object is exactly at x, y you should get the bounds for + * the returned path and test x, y against that. + * + * @param tree a {@code JTree} object + * @param x an integer giving the number of pixels horizontally from the + * left edge of the display area + * @param y an integer giving the number of pixels vertically from the top + * of the display area, minus any top margin + * @return the {@code TreePath} node closest to {@code x,y} or {@code null} + * if there is nothing currently visible + */ public abstract TreePath getClosestPathForLocation(JTree tree, int x, int y); /** - * Returns true if the tree is being edited. The item that is being - * edited can be returned by getEditingPath(). - */ + * Returns true if the tree is being edited. The item that is being + * edited can be returned by getEditingPath(). + * + * @param tree a {@code JTree} object + * @return true if {@code tree} is being edited + */ public abstract boolean isEditing(JTree tree); /** - * Stops the current editing session. This has no effect if the - * tree isn't being edited. Returns true if the editor allows the - * editing session to stop. - */ + * Stops the current editing session. This has no effect if the + * tree isn't being edited. Returns true if the editor allows the + * editing session to stop. + * + * @param tree a {@code JTree} object + * @return true if the editor allows the editing session to stop + */ public abstract boolean stopEditing(JTree tree); /** - * Cancels the current editing session. This has no effect if the - * tree isn't being edited. Returns true if the editor allows the - * editing session to stop. - */ + * Cancels the current editing session. This has no effect if the + * tree isn't being edited. + * + * @param tree a {@code JTree} object + */ public abstract void cancelEditing(JTree tree); /** - * Selects the last item in path and tries to edit it. Editing will - * fail if the CellEditor won't allow it for the selected item. - */ + * Selects the last item in path and tries to edit it. Editing will + * fail if the CellEditor won't allow it for the selected item. + * + * @param tree the {@code JTree} being edited + * @param path the {@code TreePath} to be edited + */ public abstract void startEditingAtPath(JTree tree, TreePath path); /** * Returns the path to the element that is being edited. + * + * @param tree the {@code JTree} for which to return a path + * @return a {@code TreePath} containing the path to {@code tree} */ public abstract TreePath getEditingPath(JTree tree); } diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/plaf/basic/BasicInternalFrameUI.java --- a/jdk/src/java.desktop/share/classes/javax/swing/plaf/basic/BasicInternalFrameUI.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/plaf/basic/BasicInternalFrameUI.java Tue Aug 19 10:32:16 2014 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -351,10 +351,15 @@ /** - * Installs necessary mouse handlers on newPane - * and adds it to the frame. - * Reverse process for the currentPane. - */ + * Installs necessary mouse handlers on newPane + * and adds it to the frame. + * Reverse process for the currentPane. + * + * @param currentPane this {@code Jcomponent} is the current pane being + * viewed that has mouse handlers installed + * @param newPane this {@code Jcomponent} is the pane which will be added + * and have mouse handlers installed + */ protected void replacePane(JComponent currentPane, JComponent newPane) { if(currentPane != null) { deinstallMouseHandlers(currentPane); @@ -517,11 +522,12 @@ } /// DesktopManager methods - /** Returns the proper DesktopManager. Calls getDesktopPane() to - * find the JDesktop component and returns the desktopManager from - * it. If this fails, it will return a default DesktopManager that - * should work in arbitrary parents. - */ + /** + * Returns the proper DesktopManager. Calls getDesktopPane() to + * find the JDesktop component and returns the desktopManager from + * it. If this fails, it will return a default DesktopManager that + * should work in arbitrary parents. + */ protected DesktopManager getDesktopManager() { if(frame.getDesktopPane() != null && frame.getDesktopPane().getDesktopManager() != null) @@ -539,6 +545,8 @@ * This method is called when the user wants to close the frame. * The playCloseSound Action is fired. * This action is delegated to the desktopManager. + * + * @param f the {@code JInternalFrame} being viewed */ protected void closeFrame(JInternalFrame f) { // Internal Frame Auditory Cue Activation @@ -551,6 +559,8 @@ * This method is called when the user wants to maximize the frame. * The playMaximizeSound Action is fired. * This action is delegated to the desktopManager. + * + * @param f the {@code JInternalFrame} being viewed */ protected void maximizeFrame(JInternalFrame f) { // Internal Frame Auditory Cue Activation @@ -563,6 +573,8 @@ * This method is called when the user wants to minimize the frame. * The playRestoreDownSound Action is fired. * This action is delegated to the desktopManager. + * + * @param f the {@code JInternalFrame} being viewed */ protected void minimizeFrame(JInternalFrame f) { // Internal Frame Auditory Cue Activation @@ -579,6 +591,8 @@ * This method is called when the user wants to iconify the frame. * The playMinimizeSound Action is fired. * This action is delegated to the desktopManager. + * + * @param f the {@code JInternalFrame} being viewed */ protected void iconifyFrame(JInternalFrame f) { // Internal Frame Auditory Cue Activation @@ -591,6 +605,8 @@ * This method is called when the user wants to deiconify the frame. * The playRestoreUpSound Action is fired. * This action is delegated to the desktopManager. + * + * @param f the {@code JInternalFrame} being viewed */ protected void deiconifyFrame(JInternalFrame f) { // Internal Frame Auditory Cue Activation @@ -603,15 +619,21 @@ getDesktopManager().deiconifyFrame(f); } - /** This method is called when the frame becomes selected. + /** + * This method is called when the frame becomes selected. * This action is delegated to the desktopManager. + * + * @param f the {@code JInternalFrame} being viewed */ protected void activateFrame(JInternalFrame f) { getDesktopManager().activateFrame(f); } - /** This method is called when the frame is no longer selected. - * This action is delegated to the desktopManager. - */ + /** + * This method is called when the frame is no longer selected. + * This action is delegated to the desktopManager. + * + * @param f the {@code JInternalFrame} being viewed + */ protected void deactivateFrame(JInternalFrame f) { getDesktopManager().deactivateFrame(f); } @@ -769,7 +791,7 @@ resizeDir = SOUTH; } } else { - /* the mouse press happened inside the frame, not in the + /* the mouse press happened inside the frame, not in the border */ discardRelease = true; return; diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/plaf/basic/BasicScrollBarUI.java --- a/jdk/src/java.desktop/share/classes/javax/swing/plaf/basic/BasicScrollBarUI.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/plaf/basic/BasicScrollBarUI.java Tue Aug 19 10:32:16 2014 -0700 @@ -93,8 +93,10 @@ private final static int scrollSpeedThrottle = 60; // delay in milli seconds - /** True indicates a middle click will absolutely position the - * scrollbar. */ + /** + * True indicates a middle click will absolutely position the + * scrollbar. + */ private boolean supportsAbsolutePositioning; /** @@ -877,6 +879,10 @@ * Set the bounds of the thumb and force a repaint that includes * the old thumbBounds and the new one. * + * @param x set the x location of the thumb + * @param y set the y location of the thumb + * @param width set the width of the thumb + * @param height set the height of the thumb * @see #getThumbBounds */ protected void setThumbBounds(int x, int y, int width, int height) diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/plaf/basic/BasicSliderUI.java --- a/jdk/src/java.desktop/share/classes/javax/swing/plaf/basic/BasicSliderUI.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/plaf/basic/BasicSliderUI.java Tue Aug 19 10:32:16 2014 -0700 @@ -656,10 +656,15 @@ } /** - * Gets the height of the tick area for horizontal sliders and the width of the - * tick area for vertical sliders. BasicSliderUI uses the returned value to - * determine the tick area rectangle. If you want to give your ticks some room, - * make this larger than you need and paint your ticks away from the sides in paintTicks(). + * Gets the height of the tick area for horizontal sliders and the width of + * the tick area for vertical sliders. BasicSliderUI uses the returned value + * to determine the tick area rectangle. If you want to give your ticks some + * room, make this larger than you need and paint your ticks away from the + * sides in paintTicks(). + * + * @return an integer representing the height of the tick area for + * horizontal sliders, and the width of the tick area for the vertical + * sliders */ protected int getTickLength() { return 8; @@ -867,7 +872,7 @@ * Returns the smallest value that has an entry in the label table. * * @return smallest value that has an entry in the label table, or - * null. + * null. * @since 1.6 */ protected Integer getLowestValue() { @@ -894,7 +899,11 @@ /** - * Returns the label that corresponds to the highest slider value in the label table. + * Returns the label that corresponds to the highest slider value in the + * label table. + * + * @return the label that corresponds to the highest slider value in the + * label table * @see JSlider#setLabelTable */ protected Component getLowestValueLabel() { @@ -906,7 +915,11 @@ } /** - * Returns the label that corresponds to the lowest slider value in the label table. + * Returns the label that corresponds to the lowest slider value in the + * label table. + * + * @return the label that corresponds to the lowest slider value in the + * label table * @see JSlider#setLabelTable */ protected Component getHighestValueLabel() { @@ -1166,8 +1179,14 @@ } /** - * Called for every label in the label table. Used to draw the labels for horizontal sliders. - * The graphics have been translated to labelRect.y already. + * Called for every label in the label table. Used to draw the labels for + * horizontal sliders. The graphics have been translated to labelRect.y + * already. + * + * @param g the graphics context in which to paint + * @param value the value of the slider + * @param label the component label in the label table that needs to be + * painted * @see JSlider#setLabelTable */ protected void paintHorizontalLabel( Graphics g, int value, Component label ) { @@ -1179,8 +1198,14 @@ } /** - * Called for every label in the label table. Used to draw the labels for vertical sliders. - * The graphics have been translated to labelRect.x already. + * Called for every label in the label table. Used to draw the labels for + * vertical sliders. The graphics have been translated to labelRect.x + * already. + * + * @param g the graphics context in which to paint + * @param value the value of the slider + * @param label the component label in the label table that needs to be + * painted * @see JSlider#setLabelTable */ protected void paintVerticalLabel( Graphics g, int value, Component label ) { @@ -1342,9 +1367,12 @@ } /** - * This function is called when a mousePressed was detected in the track, not - * in the thumb. The default behavior is to scroll by block. You can - * override this method to stop it from scrolling or to add additional behavior. + * This function is called when a mousePressed was detected in the track, + * not in the thumb. The default behavior is to scroll by block. You can + * override this method to stop it from scrolling or to add additional + * behavior. + * + * @param dir the direction and number of blocks to scroll */ protected void scrollDueToClickInTrack( int dir ) { scrollByBlock( dir ); @@ -1387,6 +1415,7 @@ * @param value the slider value to get the location for * @param trackY y-origin of the track * @param trackHeight the height of the track + * @return the y location for the specified value of the slider * @since 1.6 */ protected int yPositionForValue(int value, int trackY, int trackHeight) { @@ -1417,6 +1446,9 @@ * track at the the bottom or the top, this method sets the value to either * the minimum or maximum value of the slider, depending on if the slider * is inverted or not. + * + * @param yPos the location of the slider along the y axis + * @return the value at the y position */ public int valueForYPosition( int yPos ) { int value; @@ -1449,6 +1481,9 @@ * track at the left or the right, this method sets the value to either the * minimum or maximum value of the slider, depending on if the slider is * inverted or not. + * + * @param xPos the location of the slider along the x axis + * @return the value of the x position */ public int valueForXPosition( int xPos ) { int value; diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/plaf/basic/BasicTabbedPaneUI.java --- a/jdk/src/java.desktop/share/classes/javax/swing/plaf/basic/BasicTabbedPaneUI.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/plaf/basic/BasicTabbedPaneUI.java Tue Aug 19 10:32:16 2014 -0700 @@ -1174,6 +1174,16 @@ * this function draws the border around each tab * note that this function does now draw the background of the tab. * that is done elsewhere + * + * @param g the graphics context in which to paint + * @param tabPlacement the placement (left, right, bottom, top) of the tab + * @param tabIndex the index of the tab with respect to other tabs + * @param x the x coordinate of tab + * @param y the y coordinate of tab + * @param w the width of the tab + * @param h the height of the tab + * @param isSelected a {@code boolean} which determines whether or not + * the tab is selected */ protected void paintTabBorder(Graphics g, int tabPlacement, int tabIndex, @@ -3530,12 +3540,7 @@ else if (name =="indexForTitle") { calculatedBaseline = false; Integer index = (Integer) e.getNewValue(); - // remove the current index - // to let updateHtmlViews() insert the correct one - if (htmlViews != null) { - htmlViews.removeElementAt(index); - } - updateHtmlViews(index); + updateHtmlViews(index, false); } else if (name == "tabLayoutPolicy") { BasicTabbedPaneUI.this.uninstallUI(pane); BasicTabbedPaneUI.this.installUI(pane); @@ -3574,13 +3579,13 @@ calculatedBaseline = false; } else if (name == "indexForNullComponent") { isRunsDirty = true; - updateHtmlViews((Integer)e.getNewValue()); + updateHtmlViews((Integer)e.getNewValue(), true); } else if (name == "font") { calculatedBaseline = false; } } - private void updateHtmlViews(int index) { + private void updateHtmlViews(int index, boolean inserted) { String title = tabPane.getTitleAt(index); boolean isHTML = BasicHTML.isHTMLString(title); if (isHTML) { @@ -3588,16 +3593,24 @@ htmlViews = createHTMLVector(); } else { // Vector already exists View v = BasicHTML.createHTMLView(tabPane, title); - htmlViews.insertElementAt(v, index); + setHtmlView(v, inserted, index); } } else { // Not HTML if (htmlViews!=null) { // Add placeholder - htmlViews.insertElementAt(null, index); + setHtmlView(null, inserted, index); } // else nada! } updateMnemonics(); } + private void setHtmlView(View v, boolean inserted, int index) { + if (inserted || index >= htmlViews.size()) { + htmlViews.insertElementAt(v, index); + } else { + htmlViews.setElementAt(v, index); + } + } + // // ChangeListener // @@ -3716,7 +3729,7 @@ return; } isRunsDirty = true; - updateHtmlViews(tp.indexOfComponent(child)); + updateHtmlViews(tp.indexOfComponent(child), true); } public void componentRemoved(ContainerEvent e) { JTabbedPane tp = (JTabbedPane)e.getContainer(); diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/text/AbstractDocument.java --- a/jdk/src/java.desktop/share/classes/javax/swing/text/AbstractDocument.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/text/AbstractDocument.java Tue Aug 19 10:32:16 2014 -0700 @@ -1426,11 +1426,18 @@ // --- serialization --------------------------------------------- + @SuppressWarnings("unchecked") private void readObject(ObjectInputStream s) throws ClassNotFoundException, IOException { - s.defaultReadObject(); + ObjectInputStream.GetField f = s.readFields(); + + documentProperties = + (Dictionary) f.get("documentProperties", null); listenerList = new EventListenerList(); + data = (Content) f.get("data", null); + context = (AttributeContext) f.get("context", null); + documentFilter = (DocumentFilter) f.get("documentFilter", null); // Restore bidi structure //REMIND(bcb) This creates an initial bidi element to account for diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/text/DefaultCaret.java --- a/jdk/src/java.desktop/share/classes/javax/swing/text/DefaultCaret.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/text/DefaultCaret.java Tue Aug 19 10:32:16 2014 -0700 @@ -1516,7 +1516,30 @@ private void readObject(ObjectInputStream s) throws ClassNotFoundException, IOException { - s.defaultReadObject(); + ObjectInputStream.GetField f = s.readFields(); + + EventListenerList newListenerList = (EventListenerList) f.get("listenerList", null); + if (newListenerList == null) { + throw new InvalidObjectException("Null listenerList"); + } + listenerList = newListenerList; + component = (JTextComponent) f.get("component", null); + updatePolicy = f.get("updatePolicy", 0); + visible = f.get("visible", false); + active = f.get("active", false); + dot = f.get("dot", 0); + mark = f.get("mark", 0); + selectionTag = f.get("selectionTag", null); + selectionVisible = f.get("selectionVisible", false); + flasher = (Timer) f.get("flasher", null); + magicCaretPosition = (Point) f.get("magicCaretPosition", null); + dotLTR = f.get("dotLTR", false); + markLTR = f.get("markLTR", false); + ownsSelection = f.get("ownsSelection", false); + forceCaretPositionChange = f.get("forceCaretPositionChange", false); + caretWidth = f.get("caretWidth", 0); + aspectRatio = f.get("aspectRatio", 0.0f); + handler = new Handler(); if (!s.readBoolean()) { dotBias = Position.Bias.Forward; diff -r e9b05e933ddd -r 508779ce6619 jdk/src/java.desktop/share/classes/javax/swing/text/DefaultStyledDocument.java --- a/jdk/src/java.desktop/share/classes/javax/swing/text/DefaultStyledDocument.java Mon Aug 18 14:03:21 2014 +0100 +++ b/jdk/src/java.desktop/share/classes/javax/swing/text/DefaultStyledDocument.java Tue Aug 19 10:32:16 2014 -0700 @@ -1082,8 +1082,9 @@ private void readObject(ObjectInputStream s) throws ClassNotFoundException, IOException { - listeningStyles = new Vector

Audio System Property Keys