What about the full written specifications?

Both Blu-ray and OCAP are built on top of GEM and MHP, as well as Personal Basis Profile and Java TV. Blu-ray requires at least PBP 1.0, and OCAP's current versions require at least PBP 1.1. For GEM and MHP, you can download the specs for free at http://www.mhp.org/ by clicking on "Technical Specifications." BD-J is built on MHP/GEM 1.0 (GEM version 1.0.3 as of this writing, in March '09).

The Blu-ray specification itself, particularly part 3.2 that contains the Java definitions, is available for a fee and under a license from the BDA. Please contact them for details. The BDA licensing office has a web page at http://blu-raydisc.info.

What about OCAP?

A similar platform definition is readily available, at https://opencable.dev.java.net/servlets/ProjectProcess?tab=4. As of this writing, the OCAP stubs were "disclaimerized," that is, the text documentation of the Sun parts were replaced with a disclaimer.

Getting a BD-J Platform Definition

For a Java developer to develop BD-J applications, they must be able to read the API documentation of the platform in a human-readable form, and they need to compile applications against a "classes.zip" platform definition file. Copyright on the BD-J platform definition is held by various different parties, so unfortunately it's not presently possible to download the entire platform definition as one unified piece. Instead, you have to collect the source files that make up the platform definition yourself, from the BDA, from DVB, and from Sun Microsystems. In order to get the BDA part, you'll need to send them a request in the form of a signed document, so it might take a day or two before you can get the needed files from them.

The process of assembling the pieces into the form needed by the BD-J developer involves a number of steps. To save everybody time and effort, we've created a shell script that does this job. It's available at http://hdcookbook.com/bdj_platform/build.sh, and it's reproduced in full on this page. It contains extensive comments at the beginning of the file that explain where to obtain all of the needed parts, and how to run the shell script.

Platform Definition shell script

Here's the shell script that you can use to assemble a BD-J platform definition:

#!/bin/sh
#
#		BD-J Platform Definition
#		Bill Foote, bill.foote@sun.com, billf@jovial.com
#		Sept. 16, 2008
#
#  This shell script can be used to build a unified set of platform
#  documentation of the BD-J platform, and a set of "compilation stubs"
#  that allow applications to be compiled.  The resulting platform
#  documentation will be in HTML "javadoc" form, and will include all
#  APIs defined in or required by the Blu-ray Disc BD-ROM specification,
#  part 3.2.  In order to produce this, you will have to download the Java
#  source code that defines different parts of the platform from a variety
#  of sources, and assemble that source code as directed herein.
#
#  Certain of the Sun pieces aren't yet available as "stubs source code",
#  that is, Java source code that does not include meaninful method
#  implementations.  These are in the process of being published in Sun.
#  In the meantime, it is possible to download the reference implementation
#  of the Sun technologies in question.  These reference implementations
#  might have documentation that is slightly out of date with recent
#  specification bugfixes, but it is extremely close, and in all important
#  aspects it is adequate for BD-J development.  It's also much better than
#  other approximations available, such as using the implementation of a
#  PC-based BD-ROM player (which might contain a superset of the minimum
#  required BD-J APIs).  For now, we recommend the approach outlined in this
#  document; as the stubs source code from Sun becomes available, this document
#  will be amended (and simplified!).
#
#  You will need to obtain:
#
#     *  The BD-J JavaDocStubs, available from the Blu-ray Disc
#	 association.  An application can be found at
# 	 http://blu-raydisc.info/license_app/javadocstubs_apps.php.
#
#     *  The GEM Stubs for Packaged Media Target (GEM 1.0.3) (August 2008),
#	 available from http://www.mhp.org/mhpgem10.htm
#
#     *  The Java TV API 1.1_01 Source RI and Documentation, available
#	 from http://java.sun.com/products/javatv/ .
#
#     *  The Java TV API 1.1_01 Binary Reference Implementation and
#	 Documentation, available from http://java.sun.com/products/javatv/
#
#     *  Source code for the other Sun components, Personal Basis Profile 
#	 1.0 and JSSE for CDC 1.0.  Sun is preparing a download of these
#	 components (which will also include Java TV), but this probably
#	 won't be ready before October 2008.  In the meantime, you can get
#	 a copy of "fake" stubs that contain the correct API signatures, but
#	 that have had the API element descriptions replaced with a disclaimer.
#	 This can be downloaded from 
#	  http://hdcookbook.com/bdj_platform/fake_stubs_pbp_jsse.zip.
#
#  APIs that are not mentioned here may be a required part of Blu-ray 
#  players.  If you wish to write BD-J applications that access these APIs,
#  you'll need to extend the compilation stubs, and perhaps also the
#  javadoc documentation with these API defintions.  For example, the BD+
#  subsystem may include APIs that can be accessed by certain BD-J
#  applications, but the source of these APIs is not called out in the
#  part 3.2 specifications, so instructions on obtaining the correct version
#  of these APIs is not included here.
#
#  This build script is in the form of a shell script.  It can be directly
#  executed on any Unix-based computer (such as OS/X or Linux), and it can
#  be run on Windows in a Unix emulation environment such as Cygwin.
#
#
#   INSTALLING THE SOURCE CODE
#   ==========================
#
#
#  First, go to the directory that contains this shell script, and make
#  a directory called "originals".  You'll be copying the source code that
#  you download into this directory.
#
#  Next, obtain the BD-J JavaDocStubs from the BDA.  You'll eventually
#  get a file from the BDA called 
#  BD-ROM_Part3-2_v3.4_javadoc_080623-src-stubs.jar .  Copy this file into
#  the originals directory.
#
#  Now, get a copy of the GEM 1.0.3 stubs for the packaged media target.
#  They'll be in a file called gem_packaged_media.rar ; copy this into
#  the originals directory.  It's stored in a "RAR" archive, and many computers
#  don't have a command-line unrar tool built in, so you'll have to unpack the
#  archive manually.  On Mac, I use a program called "UnRarX", but many other
#  free unrar programs are also available.  In the originals directory, remove
#  any previous version of the directory called gem_packaged_media that might
#  exist, and then run your unrar program on gem_packaged_media.rar (e.g.
#  by double-clicking on the file).  You should now see a directory called
#  gem_packaged_media.
#
#  Get a copy of the Java TV API 1.1_01 source RI and documentation.
#  You'll get a file called jtv-1_1_01-src-doc.zip ; copy this into the
#  originals directory.  Similarly, the Java TV API 1.1_01 binary reference
#  implementation and documentation comes in a file called
#  jtv-1_1_01-bin-doc.zip; copy this into the originals directory, too.
#
#  Finally, get a copy of the "fake" PBP and JSSE stubs source code from
#  hdcookbook.com.  They'll be in a file called fake_stubs_pbp_jsse.zip ;
#  copy this into the originals directory.
#
#
#  That's it!  You've now assembled all of the pieces.  Now, just bring up
#  a shell window in the directory containing this shell script, and execute
#  it with:
#
#	sh build.sh
#
#  The shell script relies on a few very common programs:  unzip, zip, javac, 
#  and javadoc.

#
# First, do the interactive profile.  We start by unpacking all of 
# the source...
#
rm -rf tmp
mkdir tmp
cd tmp
mkdir bda
cd bda
unzip ../../originals/BD-ROM_Part3-2_v3.4_javadoc_080623-src-stubs.jar
cd ..
unzip ../originals/fake_stubs_pbp_jsse.zip
unzip ../originals/jtv-1_1_01-src-doc.zip
mkdir gem
cp -r ../originals/gem_packaged_media/interactive/src/org gem/org
unzip jtv-1_1_01-rr-src-b02-linux-x86-24_apr_2006.zip
rm jtv-1_1_01-rr-src-b02-linux-x86-24_apr_2006.zip
rm jtv-1_1_01-doc.zip
unzip ../originals/jtv-1_1_01-bin-doc.zip
mkdir jtv-binary
cd jtv-binary
mkdir tmp
cd tmp
unzip ../../jtv-1_1_01-rr-bin-b02-linux-x86-12_may_2006.zip
cd ..
unzip tmp/javatv.jar
rm -rf tmp com sun
rm javax/media/protocol/URLSourceStream.class    #  package-private class
cd ..
rm jtv-1_1_01-doc.zip
rm jtv-1_1_01-rr-bin-b02-linux-x86-12_may_2006.zip

#
# Now, still on the interactive profile, we compile the stubs.  For Java TV,
# the source code has implementation in it, so we don't compile Java TV;
# instead, we copy the Java TV class files out of the binary reference
# implementation.
rm -rf ../interactive
mkdir ../interactive
mkdir classes
cp -r jtv-binary/javax classes/javax
javac -bootclasspath classes -d classes -source 1.3 -target 1.3 \
	-sourcepath fake_stubs_pbp_jsse:gem:bda \
	`find fake_stubs_pbp_jsse -name '*.java' -print` \
	`find gem -name '*.java' -print` \
	`find bda -name '*.java' -print`
cd classes
zip -r ../../interactive/classes.zip *
cd ..
rm -rf classes
mkdir ../interactive/html
javadoc -bootclasspath ../interactive/html -d ../interactive/html \
	-source 1.3 \
	-sourcepath fake_stubs_pbp_jsse:javatv1.1_01/src/share/jmflite/classes:javatv1.1_01/src/share/javatv/classes:gem:bda \
	`find fake_stubs_pbp_jsse -name '*.java' -print` \
	`find javatv1.1_01/src/share/jmflite/classes/javax -name '*.java' -print` \
	`find javatv1.1_01/src/share/javatv/classes/javax -name '*.java' -print` \
	`find fake_stubs_pbp_jsse -name '*.java' -print` \
	`find gem -name '*.java' -print` \
	`find bda -name '*.java' -print`

cd ..
rm -rf tmp

#
#
#  Now, we do the same thing for the enhanced profile.  This is copy-paste of
#  the above, but we also remove JSSE, and grab the GEM enhanced profile.
#  ("Enhanced" is the GEM term for "without connection to the Internets").
#
#

pwd
mkdir tmp
cd tmp
mkdir bda
cd bda
unzip ../../originals/BD-ROM_Part3-2_v3.4_javadoc_080623-src-stubs.jar
cd ..
unzip ../originals/fake_stubs_pbp_jsse.zip
#  Remove JSSE:
rm -rf fake_stubs_pbp_jsse/javax/net fake_stubs_pbp_jsse/javax/security
unzip ../originals/jtv-1_1_01-src-doc.zip
mkdir gem
cp -r ../originals/gem_packaged_media/enhanced/src/org gem/org
unzip jtv-1_1_01-rr-src-b02-linux-x86-24_apr_2006.zip
rm jtv-1_1_01-rr-src-b02-linux-x86-24_apr_2006.zip
rm jtv-1_1_01-doc.zip
unzip ../originals/jtv-1_1_01-bin-doc.zip
mkdir jtv-binary
cd jtv-binary
mkdir tmp
cd tmp
unzip ../../jtv-1_1_01-rr-bin-b02-linux-x86-12_may_2006.zip
cd ..
unzip tmp/javatv.jar
rm -rf tmp com sun
rm javax/media/protocol/URLSourceStream.class    #  package-private class
cd ..
rm jtv-1_1_01-doc.zip
rm jtv-1_1_01-rr-bin-b02-linux-x86-12_may_2006.zip

#
# Now, to finish the enhanced profile, we compile the stubs.  For Java TV,
# the source code has implementation in it, so we don't compile Java TV;
# instead, we copy the Java TV class files out of the binary reference
# implementation.
rm -rf ../enhanced
mkdir ../enhanced
mkdir classes
cp -r jtv-binary/javax classes/javax
javac -bootclasspath classes -d classes -source 1.3 -target 1.3 \
	-sourcepath fake_stubs_pbp_jsse:gem:bda \
	`find fake_stubs_pbp_jsse -name '*.java' -print` \
	`find gem -name '*.java' -print` \
	`find bda -name '*.java' -print`
cd classes
zip -r ../../enhanced/classes.zip *
cd ..
rm -rf classes
mkdir ../enhanced/html
javadoc -bootclasspath ../enhanced/html -d ../enhanced/html \
	-source 1.3 \
	-sourcepath fake_stubs_pbp_jsse:javatv1.1_01/src/share/jmflite/classes:javatv1.1_01/src/share/javatv/classes:gem:bda \
	`find fake_stubs_pbp_jsse -name '*.java' -print` \
	`find javatv1.1_01/src/share/jmflite/classes/javax -name '*.java' -print` \
	`find javatv1.1_01/src/share/javatv/classes/javax -name '*.java' -print` \
	`find fake_stubs_pbp_jsse -name '*.java' -print` \
	`find gem -name '*.java' -print` \
	`find bda -name '*.java' -print`

cd ..
rm -rf tmp


echo ""
echo ""
echo "If the above ran without any serious problems, you should now have"
echo 'two directories:  "enhanced" and "interactive".  These contain the'
echo "compilation stubs and HTML javadocs for these two profiles, in the"
echo 'file "classes.zip" and the directory "html" respectively.'
echo ""
echo "You can refer to the HTML documentation, and you can use the classes.zip"
echo "file to compile BD-J applications, either using"
echo '"javac -bootclasspath classes.zip" or by configuring your IDE'
echo "appropriately."
echo ""
echo ""

# End of build.sh

-- Main.billf - 17 Sep 2008