Xj3D 2.0 VRML/X3D Code API

Package org.xj3d.core.loading

Implementation of a load manager interfaces for externally referenced file within a scene.


Interface Summary
CacheDetails A data holder class that contains information for file caching during the load process.
ContentLoadManager An abstract definition of managers for loading files that are external to the currently loading file eg Textures, inlines and protos.
FileCache Interface defining a file caching system without specifying an implementation.
LoadConstants Collection of internal constants for load manager implementors
LoadRequestHandler The handler that that the content loading thread pool will call to load a specific request.
SceneBuilder Definition of a class that is used to build scenes from parsed content.
SceneBuilderFactory Definition of a factory used to create new instances of the scene builder on demand.
ScriptLoader Abstract representation of a class that can be used to provide script loading and initlisation facilities to the browser core.
ScriptLoadStatusListener An internal listener to allow the ScriptLoader and ScriptManager to communicate load state for the scripts.
WorldLoader Independent thread used to load a world from a list of URLs and then place it in the given node.
WorldLoaderManager Independent thread used to load a world from a list of URLs and then place it in the given node.

Class Summary
ContentLoadQueue Customised queue implementation specifically designed to handle the needs of X3D/VRML external content loading by compressing multi requests for the same URL into a single structure.
LoadDetails A simple data holder class for information about a URL to load.
LoaderThreadPool A local singleton that manages all of the threads used to load content.
LoadRequest A data holder for items that are inserted into a load queue.

Package org.xj3d.core.loading Description

Implementation of a load manager interfaces for externally referenced file within a scene.

The load manager runs as a standalone handler for dealing with nodes in a VRML/X3D scene that define their contents outside of the current file. Standard implementation examples of this are Scripts, ImageTextures and Inlines.

The loader will produce a full cache and asynchronous loading mechanism for content. The loader may be interrupted to remove all the currently loading content of the scene. Caching is performed on the local machine if allowed. Most of the behaviour can be controlled to optimise it for a given machine and network connection.

To load all files, the handler makes use of Justin Couch's URIlib Java library for loading URNs and URLs. The standard java.net library is not used as it does not provide support for URNs that the universal media library needs. This package contains a number of system properties so make sure that you check and set these as well in order for this to function correctly.

This package uses the following system properties to modify its behaviour.

The default sort order is defined to be:

  1. loadURL (any loadURL() call from the SAI/EAI)
  2. textures All texture types and Background nodes, except for MovieTexture.
  3. externprotos Externproto loading
  4. scripts All scripts, regardless of whether they are locally defined or external
  5. inlines Any Inline node type
  6. create Any of the createX3DFromX or createVRMLFromURL() calls
  7. audio AudioClip nodes, but not MovieTexture
  8. movies MovieTexture node.
  9. shaders Any shader source.
  10. others Anything else not covered by one of the fixed types

In keeping with the extensible nature of Xj3D, other types may be defined as part of the sort order definition. The loadURL type is always the highest priority and cannot be changed. Specifying this in the sort order list will be ignored.

Configuring the Loader

The loader's behaviour can also be adjusted for different styles of work depending on the needs of the application. All code is designed to allow changing of the implementation so that experimentation may be performed.

Setting the loader type

URI resolution setup

The URI resolver library requires a few properties to work as required. We do not set these internally as you may wish to override the defaults or use factories rather than the properties.

Properties are used to configure the URI library about where to find handlers for different networking protocols and interpretation of content into Java objects. These allow you to turn raw bytes into something that the application understands. Sun includes a number of default implementations of these, but they are not particularly efficient or easy to use. We therefore allow you to provide your own, or use the ones that come with the URI library.

There are two properties to set: uri.content.handler.pkgs and uri.protocol.handler.pkgs. The first property defines the list of packages that are used to locate content handlers for things like images and HTML files. The second property locates the packages to look for when dealing with network protocol handlers. The value of these are a list of package names separated by the pipe character '|' and point to the root package name rather than the acutual packages. See the java.net package documentation or URIlib documentation for more details.

If you are lazy, then this is all you need to set.

  System.setProperty("uri.content.handler.pkgs", "vlc.net.content");
  System.setProperty("uri.protocol.handler.pkgs", "vlc.net.protocol");
Note that if you need to handle Inline nodes, you will probably also want to use the various factories in the org.web3d.net.content package too.

Xj3D 2.0 VRML/X3D Code API

Copyright © 2001 - 2006 Web3D Consortium