| Package | sandy.core |
| Class | public class Scene3D |
| Inheritance | Scene3D flash.events.EventDispatcher |
Supercedes deprecated World3D class.
The Scene3D object is the central point of a Sandy scene.
You can have multiple scenes.
A scene contains the object tree with groups, a camera, a light source and a canvas to draw on
var cam:Camera = new Camera3D(600, 450, 45, 0, 2000); // camera viewport height,width, fov, near plane, and far plane var mc:MovieClip = someSceneHoldingMovieClip; // Programmer must ensure it is a valid movie clip. var rootGroup = new Group("world_root_group"); // Add some child objects to the world (not shown), perhaps as follows //rootGroup.addChild(someChild); // Create the scene and render it var myScene:Scene3D = new Scene3D("scene_name", mc, cam, rootGroup); myScene.render(); //The enterFrameHandler presumably calls the myScene.render() method to render the scene for each frame. yourMovieRoot.addEventListener( Event.ENTER_FRAME, enterFrameHandler );
| Property | Defined by | ||
|---|---|---|---|
| camera : Camera3D
The camera looking at this scene.
| Scene3D | ||
| container : Sprite
The container that stores all displayable objects for this scene.
| Scene3D | ||
| light : Light3D
The Light3D object associated with this this scene.
| Scene3D | ||
| name : String [read-only]
The name of this scene.
| Scene3D | ||
| rectClipping : Boolean
Enable this property to perfectly clip your 3D scene to the viewport's dimensions with a 2D clipping
If set to
true , nothing will be drawn outside the viewport's dimensions. | Scene3D | ||
| renderer : Renderer
The renerer choosed for render this scene.
| Scene3D | ||
| root : Group | Scene3D |
| Method | Defined by | ||
|---|---|---|---|
|
Creates a new 3D scene.
| Scene3D | ||
|
dispose():Boolean
Disposes of all the scene's resources.
| Scene3D | ||
|
getVersion():String
[static]
Returns a version string ("3.1"), useful for conditional code
| Scene3D | ||
|
render(p_bUseCache:Boolean = true):void
Renders the scene in its container.
| Scene3D |
| Event | Summary | Defined by | ||
|---|---|---|---|---|
| Dispatched when a light is added to the scene. | Scene3D | |||
| Dispatched when the scene is culled. | Scene3D | |||
| Dispatched when the scene is rendered. | Scene3D | |||
| Dispatched when the display list is rendered. | Scene3D | |||
| Dispatched when the scene has finished its rendering process | Scene3D | |||
| Dispatched when the scene is updated. | Scene3D |
| camera | property |
| container | property |
public var container:Sprite
The container that stores all displayable objects for this scene.
| light | property |
light:Light3D
[read-write]The Light3D object associated with this this scene.
Implementation public function get light():Light3D
public function set light(value:Light3D):void
See also
| m_oRoot | property |
protected var m_oRoot:Group
| name | property |
name:String
[read-only]The name of this scene. This value can't be changed.
Implementation public function get name():String
| rectClipping | property |
rectClipping:Boolean
[read-write]
Enable this property to perfectly clip your 3D scene to the viewport's dimensions with a 2D clipping
If set to true
, nothing will be drawn outside the viewport's dimensions.
The default value is false
.
public function get rectClipping():Boolean
public function set rectClipping(value:Boolean):void
| renderer | property |
public var renderer:Renderer
The renerer choosed for render this scene. In the future, the actual renderer will implement an interface that developers could use to create their own rendering process.
| root | property |
root:Group
[read-write]Implementation
public function get root():Group
public function set root(value:Group):void
| Scene3D | () | constructor |
public function Scene3D(p_sName:String, p_oContainer:Sprite, p_oCamera:Camera3D = null, p_oRootNode:Group = null)
Creates a new 3D scene.
Each scene is automatically registered with the SceneLocator and must be given a unique name to make proper use of the SceneLocator registry.
Parametersp_sName:String — A unique name for this scene.
|
|
p_oContainer:Sprite — The container where the scene will be drawn.
|
|
p_oCamera:Camera3D (default = null ) — The camera for this scene.
|
|
p_oRootNode:Group (default = null ) — The root group of the scene's object tree.
|
See also
| dispose | () | method |
public function dispose():Boolean
Disposes of all the scene's resources.
This method is used to clear memory and will free up all resources of the scene and unregister it from SceneLocator.
ReturnsBoolean |
| getVersion | () | method |
public static function getVersion():String
Returns a version string ("3.1"), useful for conditional code
ReturnsString |
| render | () | method |
public function render(p_bUseCache:Boolean = true):void
Renders the scene in its container. Several events are dispatched by the scene to allows you to control the rendering pipeline SandyEvent.SCENE_UPDATE is broadcasted before the update phasis of the scenegraph. During this phasis each node updates its information and creates its local matrix if any SandyEvent.SCENE_CULL is bradcasted before the scene cull phasis. This phasis corresponds to the frustum vs nodes bounding objects visibility test. Nodes that aren't in the camera field of view, are removed from the render phasis. SandyEvent.SCENE_RENDER process the render call of the visible nodes. During this process, visible polygons/sprites are registering for the camera display to the screen. SandyEvent.SCENE_RENDER_DISPLAYLIST render the visible polygons to the screen
Parametersp_bUseCache:Boolean (default = true ) — Boolean default true, use the cache system
|
See also
| lightAdded | event |
sandy.events.SandyEvent
sandy.events.SandyEvent.LIGHT_ADDED
Dispatched when a light is added to the scene.
Defines the value of the type
property of a lightAdded
event object.
| scene_cull | event |
sandy.events.SandyEvent
sandy.events.SandyEvent.SCENE_CULL
Dispatched when the scene is culled.
Defines the value of the type
property of a scene_cull
event object.
| scene_render | event |
sandy.events.SandyEvent
sandy.events.SandyEvent.SCENE_RENDER
Dispatched when the scene is rendered.
Defines the value of the type
property of a scene_render
event object.
| scene_render_display_list | event |
sandy.events.SandyEvent
sandy.events.SandyEvent.SCENE_RENDER_DISPLAYLIST
Dispatched when the display list is rendered.
Defines the value of the type
property of a scene_render_display_list
event object.
| scene_render_finish | event |
sandy.events.SandyEvent
sandy.events.SandyEvent.SCENE_RENDER_FINISH
Dispatched when the scene has finished its rendering process
Defines the value of the type
property of a scene_render_finish
event object.
| scene_update | event |
sandy.events.SandyEvent
sandy.events.SandyEvent.SCENE_UPDATE
Dispatched when the scene is updated.
Defines the value of the type
property of a scene_update
event object.


legend:
relative publish date
absolute publish date
high deliberation quality
neutral
low deliberation quality
zoom in
zoom out
Timeline Configuration
Timeline Event Detail
Please click on any event on the above timeline.
×


{% load static html_utils i18n %} {% load message_extras %}
Your account doesn't have access to this page. To proceed, please login with an account that has access.
{% else %}Please login to see this page.
{% endif %} {% endif %}{% trans 'Sign in to start your session' %}


--- layout: base title: Computer Anonymous - San Francisco ---
Read The overview if you haven't already.
After an enjoyable first meetup at The Sycamore on Sat 5th, and a bit of discussion in irc/meatspace/twitter, it seems like we should alternate between Saturdays and Wednesdays, maybe with some space between. Let's get a calendar soon (volunteers?)
Given that The Sycamore went well last time, let's try The Willows for a similar place with slightly more space and similar food fare.
Time: Wednesday, Oct 16, 2013 at 7pm PST
Location: The Willows, 1582 Folsom Street (at 12th)
We've just gotten started! Join us on IRC if you want in. :)
Talk to us if you want to attend, or just turn up!


{% extends "tutorial.html" %} {% block pagebreadcrumb %}{{ tut.title }}{% endblock %} {% block head %} {% endblock %} {% block html5badge %} {% endblock %} {% block content %}
Creating mobile content that dazzles means balancing the amount of data downloaded against maximal visual impact. Vector graphics are a great way to deliver stunning visual results using minimal bandwidth.
Many people think of canvas as the only way to draw a mixture of vectors and rasters on the web, but there are alternatives that have some advantages. A great way to achieve vector drawing is through the use of Scalable Vector Graphics (SVG) which is a key part of HTML5.
We all know responsive design is a big part of handling varying screen sizes, and SVG is ideal for handling different size screens with ease.
SVG is a great way to present vector based line drawings and is a great complement to bitmaps, the latter being better suited for continuous tone images.
One of the most useful things about SVG is that it’s resolution independent, meaning that you don’t need to think about how many pixels you have on your device, the result will always scale and be optimized by the browser to look great.
Popular authoring tools like the Drawing application in Google Drive, Inkscape, Illustrator, Corel Draw and lots of others generate SVG so there are lots of ways to generate content. We'll dive into some ways to use SVG assets, plus some optimization tips to get you going.
Let's start with a simple scenario - you want a full page graphic to be the background of your web page. It'd be really useful to have your company logo, or anything like that full-screen in the background at all times, but of course that's super hard to do nicely with all the different screen sizes out there. So to illustrate, we'll start with the humble HTML5 logo.
The HTML5 logo is shown below - and you guessed it, it originates as an SVG file.
Click on the logo and take a look at it in any modern browser and you'll see that it scales beautifully to any size window. Try opening it up in your favorite browser, resize the window and observe that the image is crisp at any magnification. If we were to try that with a bitmap image, we'd either have to serve many different sizes for each screen we could encounter, or be forced to put up with horribly pixelated scaled images.
So what's the big deal? Well if you hadn't noticed, this is the only format that scales independently of the device we're using to look at it with. So we only need to serve one asset to our users, without ever needing to know what their screen or window size is - neat!
But wait, there's more - the HTML5 logo is just 1427 bytes! Yikes, that's so small that it will hardly dent any mobile data plan when loading it, which makes it fast to load and that makes it cheap and fast for your users!
Another nice thing about SVG files is that they can be GZIP compressed to further shrink them. When you compress SVG that way, the file extension has to be changed to ‘.svgz’. In the case of the HTML5 logo, it shrinks to just 663 bytes when compressed - and most modern browsers handle it with ease!
Note, some browsers can load the GZIP files OK but fail on loading via the <img> tag. Luckily HTTP can use GZIP compression so setting up the web server properly may be a better way to take advantage of GZIP compression.
Lets take a look at some popular mobile device screen sizes to understand the implications. Below is a table of devices that support HTML5 and SVG, their screen resolutions and the file size of a background image of the HTML5 logo using PNG and JPEG files. The Image/Vector ratio shows the reduction in size from JPEG compared with the 1427 byte SVG file and the compressed 663 byte SVG file in brackets.
| Device | Resolution | PNG image | JPEG image | Image/Vector ratio |
|---|---|---|---|---|
| iPhone 3G | 320x480 | 9.5k | 6.3k | 4.4 (9.5) |
| Nexus One | 480x800 | 15.4k | 9.8k | 6.8 (14.7) |
| DROID RAZR | 540x960 | 17.3k | 12k | 8.4 (18.1) |
| iPhone 4 | 640x960 | 20.7k | 13.2k | 9.25 (19.9) |
| iPhone 5 | 640x1136 | 21.6k | 14k | 9.8 (21.1) |
| Galaxy Nexus | 720x1280 | 24.4k | 15.8k | 11 (23.8) |
| iPad 1&2 | 1024x768 | 24.8k | 15.7k | 11 (23.7) |
| Galaxy Tab 10.1, Nexus 7 | 1280x800 | 27.1k | 17.9k | 12.5 (27) |
| Kindle Fire HD | 1920x1200 | 44.1k | 29.9k | 20.9 (45) |
| iPad new | 2048x1536 | 57.7k | 39.6k | 27.7 (59.7) |
As you can see, the size of the SVG data is significantly smaller for the example content, and what's interesting is that as the screen resolution increaases, the size advantage grows. Note that this is very simple vector content so for more complex content as the SVG file size increases, the file size advantage diminishes - but you still get the resolution independence.
With our example file on some of the latest devices we see something like a 60x advantage using compressed vector data! Also, note that these comparisons are being made between the JPEG and the SVG, rather than PNG. However, the JPEG is a lossy format which results in lower quality than either the SVG or PNG. If we were to use PNG, the advantage would be over 80x which is astounding!
But of course PNG and JPEG are not created equal. A number of optimization tips tell you to use JPEG instead of PNG, but that's not always such a great idea. Take a look at the images below. The image on the left is a PNG image of the top right part of the HTML5 logo enlarged 6x. The image on the right is the same thing but encoded with JPEG.
It's easy to see that the file size saving in JPEG comes at a cost, with color artifacts at the sharp edges - probably making your retina think it needs glasses:-) To be fair, JPEG is optimized for photos, and that's why it's not as good for vector art. In any case, the SVG version is the same as the PNG in quality so wins on all accounts - both file size and clarity.
Lets take a look at how you could use a vector file as the background of a page. One easy way is to declare your background file using CSS fixed positioning:
<style> #bg { position:fixed; top:0; left:0; width:100%; z-index: -1; } </style> <img src="HTML5-logo.svgz" id="bg" alt="HTML5 logo">Try it yourself
You'll notice that no matter what the size of the display, the image is sized nicely with crisp clean edges.
Then of course, we'd like to put some content over the background like in the example below.
But as you can see, the result is less than ideal since we can't read the text. So what do we do?
The obvious thing we need to do is make all the color in the background image be lighter. This is easily achieved by use of the CSS opacity property - or using opacity in the SVG file itself. You could make this work by simply adding this code to your CSS content:
#bg { opacity: 0.2; }
That would give you a result like so:
This solution whilst easy, is likely to be a performance pain point on a mobile device. For most existing mobile browsers, use of the opacity property can be a lot slower to draw with compared with opaque objects.
Modifying the color in the original SVG content is far better than setting opacity with CSS. Here is our HTML5 logo modified to look faded out by changing the colors used, and in the process avoiding the opacity property altogether. So the background image below looks identical to the result from changing the opacity, but will actually paint a lot faster and save us CPU time and save precious battery life in the process.
So now we have a decent grasp of some fundamentals, let's move on to some other features.
Let's say we want to build a button. We could start by creating a rectangle with nice rounded corners. Then we could add a nice linear gradient to give the button some nice texture. The code to do so could look something like:
<svg xmlns="http://www.w3.org/2000/svg"> <defs> <linearGradient id="blueshiny"> <stop stop-color="#a0caf6" offset="0"/> <stop stop-color="#1579df" offset="0.5" /> <stop stop-color="#1675d6" offset="0.5"/> <stop stop-color="#115ca9" offset="1"/> </linearGradient> </defs> <g id="button" onclick="alert('ouch!');"> <rect fill="url(#blueshiny)" width="198" height="83" x="3" y="4" rx="15" /> <text x="100" y="55" fill="white" font-size="18pt" text-anchor="middle">Press me</text> </g> </svg>
The resultant button would end up with something like this:
Notice how the gradient we've added goes from left to right. This is the default gradient direction in SVG. But we can do better, for a couple of different reasons: aesthetics and performance. Let's try to change the gradient direction to make it look a bit nicer. Setting the 'x1', 'y1', 'x2', and 'y2' attributes on the linear gradient controls the direction of the fill color.
Setting just the 'y2' attribute lets us change the gradient to be diagonal. So this small code change:
<linearGradient id="blueshiny" y2="1">
gives us a different look for our button, it ends up looking like the image below.
We can also easily change the gradient to go from top to bottom with this small code change:
<linearGradient id="blueshiny" x2="0" y2="1">
and that ends up looking like the image below.
So what's with all the discussion about different angles of the gradient I hear you ask?
Tip: use top to bottom gradients for better performance.
Well it turns out that the last example - the one with the gradient running from top to bottom is the fastest to draw on most devices. It's a very little known secret amongst the graphic geeks who write browser code that vertical (top to bottom) gradients paint almost as fast as a solid color. (The reason is that painting an object is done in horizontal lines down the page - and the guts of the drawing code understand that the color doesn't change across each line, and so they optimize it).
So when you choose to use gradients in your page design, vertical gradients will be faster and use less battery as a side effect. This speedup applies to CSS gradients as well, so it's not just an SVG thing.
Note, that radial gradients should be avoided unless you know they'll be hardware accelerated - in software they are painfully slow.
If we feel really adventurous with this new gradient knowledge, then we can perhaps add a cool gradient behind our HTML5 logo by adding the code below:
<defs> <linearGradient id="grad1" x2="0" y2="1"> <stop stop-color="#FBE6FB" offset="0" /> <stop stop-color="#CCCCFF" offset="0.2" /> <stop stop-color="#CCFFCC" offset="0.4" /> <stop stop-color="#FFFFCC" offset="0.6" /> <stop stop-color="#FFEDCC" offset="0.8" /> <stop stop-color="#FFCCCC" offset="1" /> </linearGradient> </defs> <rect x="-200" y="-160" width="910" height="830" fill="url(#grad1)"/>
The code above adds a faded vertical linear gradient to the backgound of our HTML5 logo to give a subtle multi-color tinge that runs fast - as fast as a solid color background.
Note, also that the choice of the size of the background rectangle guarantees the color fills the screens on all of our mobile devices listed at the start of this article (their screen aspect ratios range from 10/16 through 18/10).
If you load the content in a desktop browser and resize to extreme aspect ratios, you'll see white bars appear at the top/bottom or left/right sides. Anyway, after the code changes made above the resultant background will look like this:
By now you might be wondering what's the point of using an SVG gradient as the backdrop for your page. Indeed it might make sense to do that with CSS gradients, but one advantage of SVG is that the gradient itself lives in the DOM. This means that you can modify it with script, but more importantly you can take advantage of SVG's built in animation capability to add subtle changes to your content.
As an example, we'll modify our colorful HTML5 logo by changing the linear gradient definition to the code below:
<linearGradient id="grad1" x2="0" y2="1"> <stop stop-color="#FBE6FB" offset="0"> <animate attributeName="stop-color" values="#FBE6FB;#CCCCFF;#CCFFCC;#FFFFCC;#FFEDCC;#FFCCCC;#FBE6FB" begin="0s" dur="20s" repeatCount="indefinite"/> </stop> <stop stop-color="#CCCCFF" offset="0.2"> <animate attributeName="stop-color" values="#CCCCFF;#CCFFCC;#FFFFCC;#FFEDCC;#FFCCCC;#FBE6FB;#CCCCFF" begin="0s" dur="20s" repeatCount="indefinite"/> </stop> <stop stop-color="#CCFFCC" offset="0.4"> <animate attributeName="stop-color" values="#CCFFCC;#FFFFCC;#FFEDCC;#FFCCCC;#FBE6FB;#CCCCFF;#CCFFCC" begin="0s" dur="20s" repeatCount="indefinite"/> </stop> <stop stop-color="#FFFFCC" offset="0.6"> <animate attributeName="stop-color" values="#FFFFCC;#FFEDCC;#FFCCCC;#FBE6FB;#CCCCFF;#CCFFCC;#FFFFCC" begin="0s" dur="20s" repeatCount="indefinite"/> </stop> <stop stop-color="#FFEDCC" offset="0.8"> <animate attributeName="stop-color" values="#FFEDCC;#FFCCCC;#FBE6FB;#CCCCFF;#CCFFCC;#FFFFCC;#FFEDCC" begin="0s" dur="20s" repeatCount="indefinite"/> </stop> <stop stop-color="#FFCCCC" offset="1"> <animate attributeName="stop-color" values="#FFCCCC;#FBE6FB;#CCCCFF;#CCFFCC;#FFFFCC;#FFEDCC;#FFCCCC" begin="0s" dur="20s" repeatCount="indefinite"/> </stop> </linearGradient>
Take a look at the image below to see the result of these changes above.
The code is changing the colors of our linear gradient through all the different color stops we've defined in a continuous cycle that takes 20 seconds to run. The effect of that is that the gradient looks like it's moving up the page in a continuous motion that never stops.
The beauty of this is that there's no script required! That's why it runs as a referenced image from this page, but also it reduces workload on a mobile CPU by removing the need for script.
Also, the browser itself can take advantage of its knowledge of the painting to ensure minimal CPU overhead is used to do the fancy animation.
There is one caveat: some browsers don't handle this style of animation at all, but in that case you'll still get a nice colored background but it just won't change - this could be worked around by using script (and requestAnimationFrame) but that's a bit beyond this article.
One more thing to note, is that the uncompressed SVG file for this example is only 2922 bytes - incredibly small to supply such a rich graphics effect, keeping your users and those data plans happy in the process.
There are many cases where SVG is less than ideal, photos and videos being better represented in other formats. Text is another one, where native HTML and CSS work much better in general. However, as a tool in the arsenal for line drawn artwork it can be the ideal choice.
We've touched on a few basic fundamental uses for SVG graphics, showing how easy it is to generate tiny content that provides full screen vivid graphics with a minimal amount of download. Small enhancements to the content can create amazing graphical results easily with trivial amounts of markup. In the next article we'll explore some more details about how the animation built into SVG can be used for more simple and powerful effects and compare the use of canvas with SVG to choose the right tool for authoring your mobile graphics site.


public abstract class AsynchronousFileChannel extends Object implements AsynchronousChannel
An asynchronous file channel is created when a file is opened by invoking
one of the open
methods defined by this class. The file contains
a variable-length sequence of bytes that can be read and written and whose
current size can be queried
. The size of the file increases
when bytes are written beyond its current size; the size of the file decreases
when it is truncated
.
An asynchronous file channel does not have a current position
within the file. Instead, the file position is specified to each read and
write method that initiates asynchronous operations. A CompletionHandler
is specified as a parameter and is invoked to consume the result of the I/O
operation. This class also defines read and write methods that initiate
asynchronous operations, returning a Future
to represent the pending
result of the operation. The Future
may be used to check if the
operation has completed, wait for its completion, and retrieve the result.
In addition to read and write operations, this class defines the following operations:
Updates made to a file may be forced
out
to the underlying storage device, ensuring that data are not
lost in the event of a system crash.
A region of a file may be locked
against
access by other programs.
An AsynchronousFileChannel
is associated with a thread pool to
which tasks are submitted to handle I/O events and dispatch to completion
handlers that consume the results of I/O operations on the channel. The
completion handler for an I/O operation initiated on a channel is guaranteed
to be invoked by one of the threads in the thread pool (This ensures that the
completion handler is run by a thread with the expected identity).
Where an I/O operation completes immediately, and the initiating thread is
itself a thread in the thread pool, then the completion handler may be invoked
directly by the initiating thread. When an AsynchronousFileChannel
is
created without specifying a thread pool then the channel is associated with
a system-dependent default thread pool that may be shared with other
channels. The default thread pool is configured by the system properties
defined by the AsynchronousChannelGroup
class.
Channels of this type are safe for use by multiple concurrent threads. The
close
method may be invoked at any time, as specified
by the Channel
interface. This causes all outstanding asynchronous
operations on the channel to complete with the exception AsynchronousCloseException
. Multiple read and write operations may be
outstanding at the same time. When multiple read and write operations are
outstanding then the ordering of the I/O operations, and the order that the
completion handlers are invoked, is not specified; they are not, in particular,
guaranteed to execute in the order that the operations were initiated. The
ByteBuffers
used when reading or writing are not
safe for use by multiple concurrent I/O operations. Furthermore, after an I/O
operation is initiated then care should be taken to ensure that the buffer is
not accessed until after the operation has completed.
As with FileChannel
, the view of a file provided by an instance of
this class is guaranteed to be consistent with other views of the same file
provided by other instances in the same program. The view provided by an
instance of this class may or may not, however, be consistent with the views
seen by other concurrently-running programs due to caching performed by the
underlying operating system and delays induced by network-filesystem protocols.
This is true regardless of the language in which these other programs are
written, and whether they are running on the same machine or on some other
machine. The exact nature of any such inconsistencies are system-dependent
and are therefore unspecified.
| Modifier | Constructor and Description |
|---|---|
protected |
AsynchronousFileChannel()
Initializes a new instance of this class.
|
| Modifier and Type | Method and Description |
|---|---|
abstract void |
force(boolean metaData)
Forces any updates to this channel's file to be written to the storage
device that contains it.
|
Future<FileLock> |
lock()
Acquires an exclusive lock on this channel's file.
|
<A> void |
lock(A attachment,
CompletionHandler<FileLock,? super A> handler)
Acquires an exclusive lock on this channel's file.
|
abstract Future<FileLock> |
lock(long position,
long size,
boolean shared)
Acquires a lock on the given region of this channel's file.
|
abstract <A> void |
lock(long position,
long size,
boolean shared,
A attachment,
CompletionHandler<FileLock,? super A> handler)
Acquires a lock on the given region of this channel's file.
|
static AsynchronousFileChannel |
open(Path file,
OpenOption... options)
Opens or creates a file for reading and/or writing, returning an
asynchronous file channel to access the file.
|
static AsynchronousFileChannel |
open(Path file,
Set<? extends OpenOption> options,
ExecutorService executor,
FileAttribute<?>... attrs)
Opens or creates a file for reading and/or writing, returning an
asynchronous file channel to access the file.
|
abstract Future<Integer> |
read(ByteBuffer dst,
long position)
Reads a sequence of bytes from this channel into the given buffer,
starting at the given file position.
|
abstract <A> void |
read(ByteBuffer dst,
long position,
A attachment,
CompletionHandler<Integer,? super A> handler)
Reads a sequence of bytes from this channel into the given buffer,
starting at the given file position.
|
abstract long |
size()
Returns the current size of this channel's file.
|
abstract AsynchronousFileChannel |
truncate(long size)
Truncates this channel's file to the given size.
|
FileLock |
tryLock()
Attempts to acquire an exclusive lock on this channel's file.
|
abstract FileLock |
tryLock(long position,
long size,
boolean shared)
Attempts to acquire a lock on the given region of this channel's file.
|
abstract Future<Integer> |
write(ByteBuffer src,
long position)
Writes a sequence of bytes to this channel from the given buffer, starting
at the given file position.
|
abstract <A> void |
write(ByteBuffer src,
long position,
A attachment,
CompletionHandler<Integer,? super A> handler)
Writes a sequence of bytes to this channel from the given buffer, starting
at the given file position.
|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
close
protected AsynchronousFileChannel()
public static AsynchronousFileChannel open(Path file, Set<? extends OpenOption> options, ExecutorService executor, FileAttribute<?>... attrs) throws IOException
The options
parameter determines how the file is opened.
The READ
and WRITE
options determines if the file should be opened for reading and/or
writing. If neither option is contained in the array then an existing file
is opened for reading.
In addition to READ
and WRITE
, the following options
may be present:
| Option | Description |
|---|---|
TRUNCATE_EXISTING |
When opening an existing file, the file is first truncated to a size of 0 bytes. This option is ignored when the file is opened only for reading. |
CREATE_NEW |
If this option is present then a new file is created, failing if the file already exists. When creating a file the check for the existence of the file and the creation of the file if it does not exist is atomic with respect to other file system operations. This option is ignored when the file is opened only for reading. |
CREATE |
If this option is present then an existing file is opened if it
exists, otherwise a new file is created. When creating a file the check
for the existence of the file and the creation of the file if it does
not exist is atomic with respect to other file system operations. This
option is ignored if the CREATE_NEW option is also present or
the file is opened only for reading. |
DELETE_ON_CLOSE |
When this option is present then the implementation makes a
best effort attempt to delete the file when closed by the
the close method. If the close method is not
invoked then a best effort attempt is made to delete the file
when the Java virtual machine terminates. |
SPARSE |
When creating a new file this option is a hint that the new file will be sparse. This option is ignored when not creating a new file. |
SYNC |
Requires that every update to the file's content or metadata be written synchronously to the underlying storage device. (see Synchronized I/O file integrity). |
DSYNC |
Requires that every update to the file's content be written synchronously to the underlying storage device. (see Synchronized I/O file integrity). |
An implementation may also support additional options.
The executor
parameter is the ExecutorService
to
which tasks are submitted to handle I/O events and dispatch completion
results for operations initiated on resulting channel.
The nature of these tasks is highly implementation specific and so care
should be taken when configuring the Executor
. Minimally it
should support an unbounded work queue and should not run tasks on the
caller thread of the execute
method.
Shutting down the executor service while the channel is open results in
unspecified behavior.
The attrs
parameter is an optional array of file file-attributes
to set atomically when creating the file.
The new channel is created by invoking the newFileChannel
method on the
provider that created the Path
.
file
- The path of the file to open or createoptions
- Options specifying how the file is openedexecutor
- The thread pool or null
to associate the channel with
the default thread poolattrs
- An optional list of file attributes to set atomically when
creating the fileIllegalArgumentException
- If the set contains an invalid combination of optionsUnsupportedOperationException
- If the file
is associated with a provider that does not
support creating asynchronous file channels, or an unsupported
open option is specified, or the array contains an attribute that
cannot be set atomically when creating the fileIOException
- If an I/O error occursSecurityException
- If a security manager is installed and it denies an
unspecified permission required by the implementation.
In the case of the default provider, the SecurityManager.checkRead(String)
method is invoked to check
read access if the file is opened for reading. The SecurityManager.checkWrite(String)
method is invoked to check
write access if the file is opened for writingpublic static AsynchronousFileChannel open(Path file, OpenOption... options) throws IOException
An invocation of this method behaves in exactly the same way as the invocation
ch.open
(file, opts, null, new FileAttribute<?>[0]);
where opts
is a Set
containing the options specified to
this method.
The resulting channel is associated with default thread pool to which tasks are submitted to handle I/O events and dispatch to completion handlers that consume the result of asynchronous operations performed on the resulting channel.
file
- The path of the file to open or createoptions
- Options specifying how the file is openedIllegalArgumentException
- If the set contains an invalid combination of optionsUnsupportedOperationException
- If the file
is associated with a provider that does not
support creating file channels, or an unsupported open option is
specifiedIOException
- If an I/O error occursSecurityException
- If a security manager is installed and it denies an
unspecified permission required by the implementation.
In the case of the default provider, the SecurityManager.checkRead(String)
method is invoked to check
read access if the file is opened for reading. The SecurityManager.checkWrite(String)
method is invoked to check
write access if the file is opened for writingpublic abstract long size() throws IOException
ClosedChannelException
- If this channel is closedIOException
- If some other I/O error occurspublic abstract AsynchronousFileChannel truncate(long size) throws IOException
If the given size is less than the file's current size then the file is truncated, discarding any bytes beyond the new end of the file. If the given size is greater than or equal to the file's current size then the file is not modified.
size
- The new size, a non-negative byte countNonWritableChannelException
- If this channel was not opened for writingClosedChannelException
- If this channel is closedIllegalArgumentException
- If the new size is negativeIOException
- If some other I/O error occurspublic abstract void force(boolean metaData) throws IOException
If this channel's file resides on a local storage device then when this method returns it is guaranteed that all changes made to the file since this channel was created, or since this method was last invoked, will have been written to that device. This is useful for ensuring that critical information is not lost in the event of a system crash.
If the file does not reside on a local device then no such guarantee is made.
The metaData
parameter can be used to limit the number of
I/O operations that this method is required to perform. Passing
false
for this parameter indicates that only updates to the
file's content need be written to storage; passing true
indicates that updates to both the file's content and metadata must be
written, which generally requires at least one more I/O operation.
Whether this parameter actually has any effect is dependent upon the
underlying operating system and is therefore unspecified.
Invoking this method may cause an I/O operation to occur even if the channel was only opened for reading. Some operating systems, for example, maintain a last-access time as part of a file's metadata, and this time is updated whenever the file is read. Whether or not this is actually done is system-dependent and is therefore unspecified.
This method is only guaranteed to force changes that were made to this channel's file via the methods defined in this class.
metaData
- If true
then this method is required to force changes
to both the file's content and metadata to be written to
storage; otherwise, it need only force content changes to be
writtenClosedChannelException
- If this channel is closedIOException
- If some other I/O error occurspublic abstract <A> void lock(long position, long size, boolean shared, A attachment, CompletionHandler<FileLock,? super A> handler)
This method initiates an operation to acquire a lock on the given
region of this channel's file. The handler
parameter is a
completion handler that is invoked when the lock is acquired (or the
operation fails). The result passed to the completion handler is the
resulting FileLock
.
The region specified by the position
and size
parameters need not be contained within, or even overlap, the actual
underlying file. Lock regions are fixed in size; if a locked region
initially contains the end of the file and the file grows beyond the
region then the new portion of the file will not be covered by the lock.
If a file is expected to grow in size and a lock on the entire file is
required then a region starting at zero, and no smaller than the
expected maximum size of the file, should be locked. The two-argument
lock(Object,CompletionHandler)
method simply locks a region
of size Long.MAX_VALUE
. If a lock that overlaps the requested
region is already held by this Java virtual machine, or this method has
been invoked to lock an overlapping region and that operation has not
completed, then this method throws OverlappingFileLockException
.
Some operating systems do not support a mechanism to acquire a file lock in an asynchronous manner. Consequently an implementation may acquire the file lock in a background thread or from a task executed by a thread in the associated thread pool. If there are many lock operations outstanding then it may consume threads in the Java virtual machine for indefinite periods.
Some operating systems do not support shared locks, in which case a
request for a shared lock is automatically converted into a request for
an exclusive lock. Whether the newly-acquired lock is shared or
exclusive may be tested by invoking the resulting lock object's isShared
method.
File locks are held on behalf of the entire Java virtual machine. They are not suitable for controlling access to a file by multiple threads within the same virtual machine.
A
- The type of the attachmentposition
- The position at which the locked region is to start; must be
non-negativesize
- The size of the locked region; must be non-negative, and the sum
position
+ size
must be non-negativeshared
- true
to request a shared lock, in which case this
channel must be open for reading (and possibly writing);
false
to request an exclusive lock, in which case this
channel must be open for writing (and possibly reading)attachment
- The object to attach to the I/O operation; can be null
handler
- The handler for consuming the resultOverlappingFileLockException
- If a lock that overlaps the requested region is already held by
this Java virtual machine, or there is already a pending attempt
to lock an overlapping regionIllegalArgumentException
- If the preconditions on the parameters do not holdNonReadableChannelException
- If shared
is true but this channel was not opened for readingNonWritableChannelException
- If shared
is false but this channel was not opened for writingpublic final <A> void lock(A attachment, CompletionHandler<FileLock,? super A> handler)
This method initiates an operation to acquire a lock on the given
region of this channel's file. The handler
parameter is a
completion handler that is invoked when the lock is acquired (or the
operation fails). The result passed to the completion handler is the
resulting FileLock
.
An invocation of this method of the form ch.lock(att,handler)
behaves in exactly the same way as the invocation
ch.lock
(0L, Long.MAX_VALUE, false, att, handler)
A
- The type of the attachmentattachment
- The object to attach to the I/O operation; can be null
handler
- The handler for consuming the resultOverlappingFileLockException
- If a lock is already held by this Java virtual machine, or there
is already a pending attempt to lock a regionNonWritableChannelException
- If this channel was not opened for writingpublic abstract Future<FileLock> lock(long position, long size, boolean shared)
This method initiates an operation to acquire a lock on the given
region of this channel's file. The method behaves in exactly the same
manner as the lock(long, long, boolean, Object, CompletionHandler)
method except that instead of specifying a completion handler, this
method returns a Future
representing the pending result. The
Future
's get
method returns the FileLock
on successful completion.
position
- The position at which the locked region is to start; must be
non-negativesize
- The size of the locked region; must be non-negative, and the sum
position
+ size
must be non-negativeshared
- true
to request a shared lock, in which case this
channel must be open for reading (and possibly writing);
false
to request an exclusive lock, in which case this
channel must be open for writing (and possibly reading)Future
object representing the pending resultOverlappingFileLockException
- If a lock is already held by this Java virtual machine, or there
is already a pending attempt to lock a regionIllegalArgumentException
- If the preconditions on the parameters do not holdNonReadableChannelException
- If shared
is true but this channel was not opened for readingNonWritableChannelException
- If shared
is false but this channel was not opened for writingpublic final Future<FileLock> lock()
This method initiates an operation to acquire an exclusive lock on this
channel's file. The method returns a Future
representing the
pending result of the operation. The Future
's get
method returns the FileLock
on successful completion.
An invocation of this method behaves in exactly the same way as the invocation
ch.lock
(0L, Long.MAX_VALUE, false)
Future
object representing the pending resultOverlappingFileLockException
- If a lock is already held by this Java virtual machine, or there
is already a pending attempt to lock a regionNonWritableChannelException
- If this channel was not opened for writingpublic abstract FileLock tryLock(long position, long size, boolean shared) throws IOException
This method does not block. An invocation always returns immediately,
either having acquired a lock on the requested region or having failed to
do so. If it fails to acquire a lock because an overlapping lock is held
by another program then it returns null
. If it fails to acquire
a lock for any other reason then an appropriate exception is thrown.
position
- The position at which the locked region is to start; must be
non-negativesize
- The size of the locked region; must be non-negative, and the sum
position
+ size
must be non-negativeshared
- true
to request a shared lock,
false
to request an exclusive locknull
if the lock could not be acquired
because another program holds an overlapping lockIllegalArgumentException
- If the preconditions on the parameters do not holdClosedChannelException
- If this channel is closedOverlappingFileLockException
- If a lock that overlaps the requested region is already held by
this Java virtual machine, or if another thread is already
blocked in this method and is attempting to lock an overlapping
region of the same fileNonReadableChannelException
- If shared
is true but this channel was not opened for readingNonWritableChannelException
- If shared
is false but this channel was not opened for writingIOException
- If some other I/O error occurslock(Object,CompletionHandler)
,
lock(long,long,boolean,Object,CompletionHandler)
,
tryLock()
public final FileLock tryLock() throws IOException
An invocation of this method of the form ch.tryLock()
behaves in exactly the same way as the invocation
ch.tryLock
(0L, Long.MAX_VALUE, false)
null
if the lock could not be acquired
because another program holds an overlapping lockClosedChannelException
- If this channel is closedOverlappingFileLockException
- If a lock that overlaps the requested region is already held by
this Java virtual machine, or if another thread is already
blocked in this method and is attempting to lock an overlapping
regionNonWritableChannelException
- If shared
is false but this channel was not opened for writingIOException
- If some other I/O error occurslock(Object,CompletionHandler)
,
lock(long,long,boolean,Object,CompletionHandler)
,
tryLock(long,long,boolean)
public abstract <A> void read(ByteBuffer dst, long position, A attachment, CompletionHandler<Integer,? super A> handler)
This method initiates the reading of a sequence of bytes from this
channel into the given buffer, starting at the given file position. The
result of the read is the number of bytes read or -1
if the given
position is greater than or equal to the file's size at the time that the
read is attempted.
This method works in the same manner as the AsynchronousByteChannel.read(ByteBuffer,Object,CompletionHandler)
method, except that bytes are read starting at the given file position.
If the given file position is greater than the file's size at the time
that the read is attempted then no bytes are read.
A
- The type of the attachmentdst
- The buffer into which bytes are to be transferredposition
- The file position at which the transfer is to begin;
must be non-negativeattachment
- The object to attach to the I/O operation; can be null
handler
- The handler for consuming the resultIllegalArgumentException
- If the position is negative or the buffer is read-onlyNonReadableChannelException
- If this channel was not opened for readingpublic abstract Future<Integer> read(ByteBuffer dst, long position)
This method initiates the reading of a sequence of bytes from this
channel into the given buffer, starting at the given file position. This
method returns a Future
representing the pending result of the
operation. The Future
's get
method returns
the number of bytes read or -1
if the given position is greater
than or equal to the file's size at the time that the read is attempted.
This method works in the same manner as the AsynchronousByteChannel.read(ByteBuffer)
method, except that bytes are
read starting at the given file position. If the given file position is
greater than the file's size at the time that the read is attempted then
no bytes are read.
dst
- The buffer into which bytes are to be transferredposition
- The file position at which the transfer is to begin;
must be non-negativeFuture
object representing the pending resultIllegalArgumentException
- If the position is negative or the buffer is read-onlyNonReadableChannelException
- If this channel was not opened for readingpublic abstract <A> void write(ByteBuffer src, long position, A attachment, CompletionHandler<Integer,? super A> handler)
This method works in the same manner as the AsynchronousByteChannel.write(ByteBuffer,Object,CompletionHandler)
method, except that bytes are written starting at the given file position.
If the given position is greater than the file's size, at the time that
the write is attempted, then the file will be grown to accommodate the new
bytes; the values of any bytes between the previous end-of-file and the
newly-written bytes are unspecified.
A
- The type of the attachmentsrc
- The buffer from which bytes are to be transferredposition
- The file position at which the transfer is to begin;
must be non-negativeattachment
- The object to attach to the I/O operation; can be null
handler
- The handler for consuming the resultIllegalArgumentException
- If the position is negativeNonWritableChannelException
- If this channel was not opened for writingpublic abstract Future<Integer> write(ByteBuffer src, long position)
This method initiates the writing of a sequence of bytes to this
channel from the given buffer, starting at the given file position. The
method returns a Future
representing the pending result of the
write operation. The Future
's get
method
returns the number of bytes written.
This method works in the same manner as the AsynchronousByteChannel.write(ByteBuffer)
method, except that bytes are
written starting at the given file position. If the given position is
greater than the file's size, at the time that the write is attempted,
then the file will be grown to accommodate the new bytes; the values of
any bytes between the previous end-of-file and the newly-written bytes
are unspecified.
src
- The buffer from which bytes are to be transferredposition
- The file position at which the transfer is to begin;
must be non-negativeFuture
object representing the pending resultIllegalArgumentException
- If the position is negativeNonWritableChannelException
- If this channel was not opened for writingDracula Javadoc Sample, Made with Allan Im.


Surveys contain questions as well as metadata such as study, location, and type.
{% endblock %}
{% block card_content %}
{% crispy form %}
{% endblock %}


--- layout: page title: Steffen Poltak date: 2013-02-18 22:10:25.000000000 -05:00 type: page published: true status: publish categories: [] tags: [] meta: _edit_last: '450' _wp_page_template: full-width-page.php author: login: kenny email<EMAIL_ADDRESS>display_name: kenny first_name: Kenneth last_name: Flynn ---
Steffen Poltak received his PhD in Microbiology from UNH in May 2010, and is now an assistant professor at St. Anselm College in Manchester, NH.
Research Interests
Ecology and evolution of Burkholderia and Pseudomonas aeruginosa biofilm communities
Major research questions:
What happens in bacterial populations after prolonged selection in a biofilm environment?
What beneficial mutations are acquired under biofilm conditions?
How does biofilm diversity effect population productivity?
How does biofilm diversity arise and how do new members interact? Antagonistic / Synergistic/ or Neutral
Do evolved biofilm populations harbor genotypes that have increased virulence and/or increased antibiotic resistance?
How do biofilm subpopulations interact to survive? What are there contributions to the form and function of the biofilm community? Are the interactions synergistic, antagonistic, or something in between?
My interests lie not only in the interactions seen between various genotypes seen within a species, but also between those seen between different species. The answers to these questions are essential in properly understanding the evolution of microbial communities, but more importantly they may prove vital in the treatment of chronic biofilm infections.


{% extends 'base.html' %} {% load static %} {% block content %}
{{form.description|capfirst}}
Responses: {{responseCount}}
Form Link: {{request.scheme}}://{{request.get_host}}{% url 'formsubmit' form.id %}
The form was created on {{form.created_on|date:"d-m-y"}}
Download Responses Delete Form


The Video method I used is the HTML5 native Video Player Method! This method supports Chrome, Firefox, and IE9+ on desktop and Chrome, UC, and Samsung on mobile.


May 16 2019
This Is My First Article
Spicy jalapeno bacon ipsum dolor amet chuck buffalo pastrami pork fatback tongue prosciutto meatball rump capicola swine short ribs cow venison pork chop. Prosciutto pancetta meatball, chuck kielbasa shankle burgdoggen t-bone salami cow frankfurter. Ground round pancetta ham hock pastrami leberkas meatloaf, landjaeger flank drumstick turducken. Shank ground round ribeye porchetta venison ham hock bacon short ribs shoulder. Tail ham hock chuck capicola frankfurter. Brisket sausage ham drumstick, shank meatloaf burgdoggen tri-tip picanha pork loin short loin kielbasa.
 Buffalo kielbasa jowl capicola. Pork chop sirloin turducken, meatloaf cupim andouille jerky buffalo meatball spare ribs tongue ham hock.  Rump frankfurter turkey, jerky picanha tail chuck tri-tip tenderloin pork belly kielbasa beef turducken.
Pork chop pancetta salami, turducken doner sausage tongue buffalo meatloaf kielbasa beef shoulder shank prosciutto pork. Tenderloin kevin shoulder, cow turducken alcatra short ribs brisket landjaeger shankle bacon buffalo picanha.  Meatloaf ribeye hamburger ball tip pancetta landjaeger tail shoulder corned beef prosciutto.


Sudoku Technique No.6
Pointing Out - Expert Level
So far we have been using one unit as target to do pointing out and/or fitting in, now we are going to add one dimension to it, a two-unit target!
See the board below, you can see both column 6 and row 7 are highlighted. Three empty cells and two missing numbers, 4 and 6, in the two-unit target. It seems locked: if 4 goes to 71 then 83 is 6 and 59 is 4, vice versa if you switch number 4 and 6. This situation often happen close to the end of the puzzle, make you attempt to guess.
No need of guess work in this case, the key of the lock is in box 4. There are two empty cells and two missing numbers, 6 and 8, in box 4. Number 8 won't help in this case but for number 6 we have 2 assumptions:
- If 6 goes to 44, then 71 cannot be 6, then 83 must be 6
- If 6 goes to 49, then 59 cannot be 6, then 83 must be 6
Both assumptions lead to the same solution: 836. Click the board to see it in animations.
If you could click the board again and look at the two-unit target, one of the three empty cells 83 is sharing between column 6 and row 7, the other two empty cells 71 and 59 are stretching out like 2 wings. I call it Angel's Wings. When locate Angel's Wings, we need a pointer that can point out both of the wings at the same time box 4 is just what we need, with its 44 point out 71 and 49 point out 59. I call it Double Pointer.
When you find Double Pointers that can point out both of the Angel's Wings, you find the angel!
In the board below, the angel hides in column 2 and row 6, but it needs two cell pointer 16 and 81 to reveal the Angel's Wings, head in 48, wings in 68 and 75, click the board to see it. Box 9 is the Double Pointer that points out both of the wings 68 and 75, we find the angel 6 in 48.
Box 9 also shows you the beauty of Double Pointer: it does not matter how many empty cells in the pointer unit, as long as all the empty cells can form two beams pointing to two directions.
Another example, this time the angel hides in box 2 and row 1, it takes fitter 1 and 9 in column 5 to reveal the Angel's Wings. Row 4 does the double pointing job and we find the angel 4 in 21.
Revealing Angel's Wings can be complicated, click the board below to see how it's revealed in column 4 and row 1, and click the board again to see how column 8 does its double pointing.
Finding the Double Pointer is not always easy either, click the board below to see Angel's Wings in column 1 and row 1, and click the board again to see how box 5 comes to be the Double Pointer.
And Double Pointers, relay, click the board below to see Angel's Wings in column 4 and row 7, and click the board again to see how Double Pointer row 5 points out one wing 83, relays to box 9, which relays to column 2, which points out the other wing 27, finally we find angel 6 in 81.
That's the Angel's Wings with Double Pointers, a brand new technique, but think about it, it's still Pointing Out technique, extended into two-dimension!
The puzzles in this post are from http://school.maths.uwa.edu.au/~gordon/sudokumin.php The work is licensed under a Creative Commons Attribution 2.5 License. Attribution goes to Gordon Royle and The University of Western Australia.


org.apache.thrift.protocol
Class TBinaryProtocol
java.lang.Object
org.apache.thrift.protocol.TProtocol
org.apache.thrift.protocol.TBinaryProtocol
public class TBinaryProtocol
- extends TProtocol
Binary protocol implementation for thrift.
| Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
VERSION_MASK
protected static final int VERSION_MASK
- See Also:
- Constant Field Values
VERSION_1
protected static final int VERSION_1
- See Also:
- Constant Field Values
strictRead_
protected boolean strictRead_
strictWrite_
protected boolean strictWrite_
readLength_
protected int readLength_
checkReadLength_
protected boolean checkReadLength_
TBinaryProtocol
public TBinaryProtocol(TTransport trans)
- Constructor
TBinaryProtocol
public TBinaryProtocol(TTransport trans,
boolean strictRead,
boolean strictWrite)
writeMessageBegin
public void writeMessageBegin(TMessage message)
throws TException
- Description copied from class:
TProtocol
- Writing methods.
- Specified by:
writeMessageBegin
in class TProtocol
- Throws:
TException
writeMessageEnd
public void writeMessageEnd()
- Specified by:
writeMessageEnd
in class TProtocol
writeStructBegin
public void writeStructBegin(TStruct struct)
- Specified by:
writeStructBegin
in class TProtocol
writeStructEnd
public void writeStructEnd()
- Specified by:
writeStructEnd
in class TProtocol
writeFieldBegin
public void writeFieldBegin(TField field)
throws TException
- Specified by:
writeFieldBegin
in class TProtocol
- Throws:
TException
writeFieldEnd
public void writeFieldEnd()
- Specified by:
writeFieldEnd
in class TProtocol
writeFieldStop
public void writeFieldStop()
throws TException
- Specified by:
writeFieldStop
in class TProtocol
- Throws:
TException
writeMapBegin
public void writeMapBegin(TMap map)
throws TException
- Specified by:
writeMapBegin
in class TProtocol
- Throws:
TException
writeMapEnd
public void writeMapEnd()
- Specified by:
writeMapEnd
in class TProtocol
writeListBegin
public void writeListBegin(TList list)
throws TException
- Specified by:
writeListBegin
in class TProtocol
- Throws:
TException
writeListEnd
public void writeListEnd()
- Specified by:
writeListEnd
in class TProtocol
writeSetBegin
public void writeSetBegin(TSet set)
throws TException
- Specified by:
writeSetBegin
in class TProtocol
- Throws:
TException
writeSetEnd
public void writeSetEnd()
- Specified by:
writeSetEnd
in class TProtocol
writeBool
public void writeBool(boolean b)
throws TException
- Specified by:
writeBool
in class TProtocol
- Throws:
TException
writeByte
public void writeByte(byte b)
throws TException
- Specified by:
writeByte
in class TProtocol
- Throws:
TException
writeI16
public void writeI16(short i16)
throws TException
- Specified by:
writeI16
in class TProtocol
- Throws:
TException
writeI32
public void writeI32(int i32)
throws TException
- Specified by:
writeI32
in class TProtocol
- Throws:
TException
writeI64
public void writeI64(long i64)
throws TException
- Specified by:
writeI64
in class TProtocol
- Throws:
TException
writeDouble
public void writeDouble(double dub)
throws TException
- Specified by:
writeDouble
in class TProtocol
- Throws:
TException
writeString
public void writeString(java.lang.String str)
throws TException
- Specified by:
writeString
in class TProtocol
- Throws:
TException
writeBinary
public void writeBinary(java.nio.ByteBuffer bin)
throws TException
- Specified by:
writeBinary
in class TProtocol
- Throws:
TException
readMessageBegin
public TMessage readMessageBegin()
throws TException
- Reading methods.
- Specified by:
readMessageBegin
in class TProtocol
- Throws:
TException
readMessageEnd
public void readMessageEnd()
- Specified by:
readMessageEnd
in class TProtocol
readStructBegin
public TStruct readStructBegin()
- Specified by:
readStructBegin
in class TProtocol
readStructEnd
public void readStructEnd()
- Specified by:
readStructEnd
in class TProtocol
readFieldBegin
public TField readFieldBegin()
throws TException
- Specified by:
readFieldBegin
in class TProtocol
- Throws:
TException
readFieldEnd
public void readFieldEnd()
- Specified by:
readFieldEnd
in class TProtocol
readMapBegin
public TMap readMapBegin()
throws TException
- Specified by:
readMapBegin
in class TProtocol
- Throws:
TException
readMapEnd
public void readMapEnd()
- Specified by:
readMapEnd
in class TProtocol
readListBegin
public TList readListBegin()
throws TException
- Specified by:
readListBegin
in class TProtocol
- Throws:
TException
readListEnd
public void readListEnd()
- Specified by:
readListEnd
in class TProtocol
readSetBegin
public TSet readSetBegin()
throws TException
- Specified by:
readSetBegin
in class TProtocol
- Throws:
TException
readSetEnd
public void readSetEnd()
- Specified by:
readSetEnd
in class TProtocol
readBool
public boolean readBool()
throws TException
- Specified by:
readBool
in class TProtocol
- Throws:
TException
readByte
public byte readByte()
throws TException
- Specified by:
readByte
in class TProtocol
- Throws:
TException
readI16
public short readI16()
throws TException
- Specified by:
readI16
in class TProtocol
- Throws:
TException
readI32
public int readI32()
throws TException
- Specified by:
readI32
in class TProtocol
- Throws:
TException
readI64
public long readI64()
throws TException
- Specified by:
readI64
in class TProtocol
- Throws:
TException
readDouble
public double readDouble()
throws TException
- Specified by:
readDouble
in class TProtocol
- Throws:
TException
readString
public java.lang.String readString()
throws TException
- Specified by:
readString
in class TProtocol
- Throws:
TException
readStringBody
public java.lang.String readStringBody(int size)
throws TException
- Throws:
TException
readBinary
public java.nio.ByteBuffer readBinary()
throws TException
- Specified by:
readBinary
in class TProtocol
- Throws:
TException
setReadLength
public void setReadLength(int readLength)
checkReadLength
protected void checkReadLength(int length)
throws TException
- Throws:
TException


nbres:
NetBeans, as a large Java application with a sophisticated module system and a strong framework for maintaining inter-module compatibility, has a specialized infrastructure for physically loading the classes that produce the application. It uses class loaders to manage the interactions between modules.
While developers who are accustomed to working with application servers or
other large componentized applications might already be familiar with the
purposes and basic mechanisms of class loader partitioning, many Java
developers only have experience with monolithic applications loaded entirely
from the system class path (the -classpath
parameter to
the Java VM launcher). All developers seeking to write a NetBeans module
should have some practical understanding of how NetBeans manages class
loading.
This document attempts to explain the basic system by which classes are loaded into NetBeans; and how you as a module author can take advantage of the power this system offers, without becoming a victim to some common misperceptions and mistakes.
Everything written here is nonnormative, which is to say it is not a formal part of the Modules API specification. For precise guarantees as to what you can and cannot do, as well as details on several points of manifest syntax, please read the Modules API.
The basic thing you need to understand about how modules control class loading is this:
If module B has a declared dependency on module A, then classes in B can refer to classes in A (but A cannot refer to B). If B does not have a declared dependency on A, it cannot refer to A. Furthermore, dependencies are not considered transitive for purposes of classloading: if C has a declared dependency on B, it can refer to classes in B, but not to A (unless it also declares an explicit dependency on A).
Remember: refer to here means refer to statically: compile
and link against. Source code for B should be passed the JAR for A in its
classpath when compiling. Module A can certainly use objects created by module
B, if assigned to a suitably generic interface; it just cannot link against
these specific classes in Java source code.
The same system applies to classpath-oriented calls such as
Class.getResource(String path)
.
This constraint is enforced using the parent-child relationship of class loaders. Each module has its own dedicated class loader. A NetBeans module classloader delegates only to the classloaders of modules which the module author asked to depend on.
This kind of relationship - a hierarchy of classloaders - is common in componentized Java applications. NetBeans takes the concept a little bit further: since a module can (and very often will) depend on several other modules, the classloader hierarchy is a directed acyclic graph, rather than a tree. This could be called multiple inheritance of classloaders.
There are a number of reasons for using such a system, rather than dumping everything in one big classpath. The main reason, though, is safety. If NetBeans let you use any class from any other module, you might begin relying on another module without even realizing it. This could cause sudden errors if that other module were missing from a user's installation. Declaring a module dependency prevents such a situation from arising.
Here is a trivial summary of the situation:
Manifest-Version: 1.0 OpenIDE-Module: org.netbeans.modules.a
public abstract class A {/* ... */} // ... public static void useSomeA(A a) {/* ... */}
Manifest-Version: 1.0 OpenIDE-Module: org.netbeans.modules.b OpenIDE-Module-Module-Dependencies: org.netbeans.modules.a
public class B extends A {/* ... */} // ... useSomeA(new B());
This basic rule covers the bulk of the situations you will encounter. There are some further reasons why you might not be able to access certain classes, but you can probably stop reading now unless you actually run into problems.
Class-Path
Commonly a NetBeans module will serve as a wrapper for an independent library, or will use one or more separate libraries as part of its implementation or API. Forcing all classes and resources used by a module to be packed together into the module JAR is generally undesirable for reasons of maintenance and clarity. Sometimes it may even violate license terms of a library to modify it by repackaging it into a module JAR.
NetBeans handles this situation by letting you use the Class-Path
manifest attribute defined by the
Java Extension Mechanism.
The value of the attribute consists of one or more relative paths to library
JARs, in the same directory as the module or (normally) beneath it.
Conventionally, such extensions are placed in a directory named
ext/ beneath the directory where the module is. It is a good idea
to name extension JARs precisely (i.e., include the version number).
For example, a module $cluster/modules/module.jar would refer to the extensions $cluster/modules/ext/library-a-1.0.jar and $cluster/modules/ext/library-b-1.1.jar this way:
Class-Path: ext/library-a-1.0.jar ext/library-b-1.1.jar
When you do this, the libraries are loaded from the same classloader as the main module JAR, just as if they had been unpacked and physically added to it. Classes from any of these JARs can refer to classes in the others. As a matter of style, however, you should generally refer to the libraries from the module but not refer to the module from the libraries. Modules dependent on a module with extensions can refer to its extensions too.
It is common for a module to just be a wrapper which has no classes
itself, but merely refers to a library using Class-Path
. Creating
such a wrapper module blesses the library with the flexible deployment and
maintenance qualities of a module. If there is no legal reason not to, you can
also just insert NetBeans-specific manifest attributes in any JAR and
use it as a module, without interfering with its use outside NetBeans.
Overuse of Class-Path
is a common bad habit. Use module
dependencies to express relationships between independent blocks of code;
Class-Path
should be used only when a JAR is a wholly owned part
of a module.
Never refer to the same JAR using Class-Path
from two different modules. (It will get loaded twice and could cause
strange problems.) If you think you need to, generally this just means you
have not factored out your module dependencies thoroughly: split off a third
module to hold the library.
Never try to use Class-Path
to refer to other
module JARs, or to JARs in the NetBeans lib/ directory, or
generally to any JAR you did not specifically bundle alongside your module and
your module only (for example, in an NBM package for Auto Update).
Do not be alarmed by all the "never"s; these are good guidelines to protect
you from common design mistakes, but the basic behavior of
Class-Path
is pretty simple:
If a module A has a
Class-Path
attribute listing some relative JAR paths, the effect is exactly the same as if the contents of those JARs were just copied into A's main JAR.
In a given NetBeans release, there are several libraries placed in the lib/ and core/ subdirectories of the NetBeans installation. These are referred to as startup libraries. If you need to use classes from them, just declare regular module dependencies.
In addition to use of Class-Path
, there are a couple of other
ways in which additional JARs might be added into the classloader for a
module.
Patches are JARs which may replace classes and resources in a module classloader. If a module has the code name base a.b.c, and there is a subdirectory named patches/a-b-c/ beneath the directory in which the module JAR resides, then this patch area will be scanned for JAR files to be added to the "front" of the module classloader - anything found in them will override corresponding classes or resources in the module and its extensions.
This patching facility is occasionally useful for testing modifications to installed modules, or making emergency fixes in the field, without needing to touch the master copy of the module. Modules should not be shipped with any patches, however.
Localization and branding may also affect the module classloader. A
module may load resources (such as property bundles, images, XML layers, and
so on) using the recommended internationalized lookup techniques -
NbBundle
methods, the nbresloc:
URL protocol, and so
on. Actual localizations of these resources are best placed in separate JAR
files, which must be named according to the locale and placed in a
subdirectory named locale/ beneath the directory in which the
module JAR resides. For example, a Japanese localization of a module
$cluster/modules/module.jar would be named
$cluster/modules/locale/module_ja.jar.
Analogously, a module may be branded to adjust it to use in a specific product, using essentially the same mechanism. The module just mentioned could have a few text changes made for a product branding named myapp by creating a file named $cluster/modules/locale/module_myapp.jar. Locales and brandings are orthogonal, so a Belgian French translation of text strings specific to MyApp Community Edition might be kept in $cluster/modules/locale/module_myapp_ce_fr_BE.jar.
All applicable locale and branding variants of module JARs are placed in the same classloader as the module itself. Only variant JARs which actually apply at runtime (according to the current locale and branding) will be loaded.
In addition to regular dependencies using
OpenIDE-Module-Module-Dependencies
, modules can also depend on
the existence of other modules using provide-require dependencies.
Here, one or more modules provide some arbitrary token (often the name of an
API class for which they supply implementations in Lookup); and other modules
may request that this token be available. A requesting modules can be enabled
only when at least one (perhaps more) providing module is enabled.
Provide-require dependencies have no effect on classloading. If module A provides token T, and module B requires token T, B may not refer to classes in A (unless it additionally declares a regular dependency on A).
By default when a module B declares a direct dependency on another module A, then B can access any public (or, as appropriate, protected) class in A - i.e. all of A is "in its classpath". However it is often the case that such broad access is undesirable. Module A may provide a formal API in certain packages, and use other packages for its private implementation. In this case it would not want other modules freely using its undocumented implementation classes.
For this reason, a special manifest attribute
OpenIDE-Module-Public-Packages
can be specified in A:
Manifest-Version: 1.0 OpenIDE-Module: org.netbeans.modules.a OpenIDE-Module-Specification-Version: 1.0 OpenIDE-Module-Implementation-Version: 1.0-alpha-2 OpenIDE-Module-Public-Packages: org.netbeans.api.a.**, org.netbeans.spi.a.**
This attribute tells the NetBeans module system to limit which packages from A are considered part of its API. If B declares a regular dependency on A according to its public API specification version:
Manifest-Version: 1.0 OpenIDE-Module: org.netbeans.modules.b OpenIDE-Module-Module-Dependencies: org.netbeans.modules.a > 1.0
then B can only use some packages from A: here,
org.netbeans.api.a
(and any subpackages it may have) and
org.netbeans.spi.a
(and subpackages). Module B will not
be permitted to use other packages from A, such as
org.netbeans.modules.a
; attempts to do so will just result in a
NoClassDefFoundError
when loading code from B.
This manifest goes further and prevents any packages from being available to other modules:
Manifest-Version: 1.0 OpenIDE-Module: org.netbeans.modules.a OpenIDE-Module-Public-Packages: -
You may still declare a dependency on such a module, in order to ensure that it is installed (perhaps it provides some non-Java-level service you need), but you may not import any classes from it.
There is a limited "back door" to this package restriction: if module B declares that it knows about module A's internal implementation, and is prepared to track arbitrary changes in A, then it can use any public classes from A regardless of the public package declaration. This is done using an implementation dependency:
Manifest-Version: 1.0 OpenIDE-Module: org.netbeans.modules.b OpenIDE-Module-Module-Dependencies: org.netbeans.modules.a = 1.0-alpha-2
Here module B declares that it is written to match details of A's implementation classes at that point in time. This version of B may not use any earlier or later versions of A, since there is no telling what changes to A's implementation classes there might have been. Therefore, such implementation dependencies are usually used among "friend modules" which are updated and published in clusters by a single developer or team.
Again, dependencies are not considered transitive for purposes of class loading; so package visibility from module A to module C (where C depends on B) is entirely independent of visibility from A to B - it can be computed entirely from the manifests of A and C.
Public package declarations also apply to packages contained in
Class-Path
extensions - just as if those classes were in the main
module JAR.
In summary:
If module A declares that it has a particular list of public packages, and module B declares a direct dependency on A, B can always use classes from A's public packages (if any). B may only use undeclared packages from A (implementation classes) if it declares an implementation dependency on the exact version of A.
nbres:
There is a special class loader in NetBeans referred to as the system class loader. This loader can load classes from any enabled module, as well as the JRE/JDK and all startup libraries (APIs and core). Therefore it is useful as a default class loader to be used by any code which tries to find a class by name without specific knowledge of where it may be located.
Finding the system class loader is easy using lookup:
ClassLoader syscl = Lookup.getDefault().lookup(ClassLoader.class);
This class loader is also the context class loader for every thread in the NetBeans VM, unless that thread (or a parent) explicitly set some other context class loader. Since many libraries which are independent of NetBeans (including in the JRE) are written to assume that all relevant classes can be loaded by name from the current thread's context loader, it is very useful for this loader to be the system class loader - you can specify any class in your module by name.
ClassLoader l = Thread.currentThread().getContextClassLoader(); Class c = l.loadClass("some.module.Class");
Any module class can be accessed from this loader, regardless of any
OpenIDE-Module-Public-Packages
declarations.
The system loader always represents the contents of the enabled modules in
NetBeans. If a module is newly enabled at runtime, its classes are effectively
added to the namespace of the same system ClassLoader
instance. (Note that this means that a call to Class.forName
which fails before the module is enabled may succeed afterwards.) However, if
a module is disabled at runtime, the system class loader is
reset to a new loader which does not have access to the old module.
This is necessary because it is impossible to remove classes from a loader
once they have been loaded. After a module is disabled and the loader reset, a
saved Lookup.Result
query on ClassLoader
will fire a
lookup result change, and all threads will be updated to get the new context
class loader too.
It is often useful to be able to refer to resources other than
classes in the system class loader. This is easy to do because NetBeans
defines a special URL protocol handler for just this purpose. URLs with the
nbres
protocol refer to resources in the system loader, and thus
can refer to resources present in any module JAR. This is very useful when
some declarative syntax requires a URL that should look in a module; for
example:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE filesystem PUBLIC "-//NetBeans//DTD Filesystem 1.1//EN" "http://www.netbeans.org/dtds/filesystem-1_1.dtd"> <!-- Register one DTD in the system entity catalog. --> <filesystem> <folder name="xml"> <folder name="entities"> <folder name="NetBeans"> <file name="DTD_Foo_1_0" url="nbres:/org/netbeans/modules/foo/resources/foo-1.0.dtd"> <attr name="hint.originalPublicID" stringvalue="-//NetBeans//DTD Foo 1.0//EN"/> </file> </folder> </folder> </folder> </filesystem>
There is also a related protocol nbresloc
which loads from the
system class loader but additionally performs automatic localization and
branding of the resource you specify. Various
suffixes
are inserted between the base name and the extension of the resource
(beginning with the last dot in the path, if it is in the last path
component), according to the current locale and branding. For example:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE filesystem PUBLIC "-//NetBeans//DTD Filesystem 1.1//EN" "http://www.netbeans.org/dtds/filesystem-1_1.dtd"> <!-- Add a URL to the Help menu with a localized name and icon. --> <filesystem> <folder name="Menu"> <folder name="Help"> <file name="netbeans-web-link.url" url="netbeans-web-link.url"> <attr name="SystemFileSystem.localizingBundle" stringvalue="org.netbeans.modules.url.Bundle"/> <attr name="SystemFileSystem.icon" urlvalue="nbresloc:/org/netbeans/modules/url/webLink.gif"/> </file> </folder> </folder> </filesystem>
Here NetBeans will look for the most specific applicable icon; it might for
example find org/netbeans/modules/url/webLink_ja.gif in
modules/locale/utilities_ja.jar, if Japanese localizers decided
the default icon was not intuitive for Japanese users and made a replacement.
Whenever you are asked for a URL to a displayable resource, consider using
nbresloc
in place of nbres
.
It is possible for two modules to include classes with the same (fully-qualified) names, so long as the modules have distinct code name bases.
This can be useful in case you want to ship several versions of a third-party library.
For example, you could have modules org.apache.log4j.v1
and org.apache.log4j.v2
both including org.apache.log4j.**
classes and exposing these packages as public.
Some modules can depend on and use version 1 while other modules depend on and use version 2.
Potential problems you might run into:
The context class loader will refuse to load any of the duplicated classes.
(It could not know which you meant to load.)
You would need to pass a specific ClassLoader
to any code which needed it.
nbres
-protocol URLs will similarly not work for duplicated resources.
Some third-party libraries, including Xerces, perversely use the thread context class loader
to load some classes which are in their own JARs, even though they could just use the class
loader which loaded the calling code. Such calls will fail. You can work around this by
temporarily setting the thread CCL to that of the desired library module, restoring it
in a finally
block.
A given module cannot depend on both of these library modules at once - it would not know which to load.
This section is an attempt to gather a number of the problems, questions, and misperceptions that people using the NetBeans module system have run across. In some cases an error is caused by a simple mistake that can be corrected just as simply; in other cases, you may need to consider the design of your module and how it can work smoothly in NetBeans. The developer's FAQ is likely to have more recent answers to your questions.
Loading classes from the default (root) package is disabled. You can load resources from
that package but a warning is printed. It is strongly discouraged to use the default package.
Please see the
Java Language Specification for more details.
You can suppress the warning using -J-Dorg.netbeans.ProxyClassLoader.level=1000
command
line switch.
NetBeans ignores %CLASSPATH% / $CLASSPATH environment variables
and defines its own classpath containing minimal set of classes required to start
the application using -classpath
parameter passed to JVM.
All other classes are loaded by classloaders created during runtime and briefly described
in this document.
If it is really neceseary to add more classes or resources to application classloader
--cp:a
or --cp:p
options of launcher can be used.
The reason is similar to why JDK documentation about setting the class path for
Windows or
Solaris
states that -classpath
is prefered over environment variables.
Adding classes (resources) to lib/ext/ affects all Java applications
running using this Java installation.
Use of --cp affects all modules and for example prevents the possibility
to have more modules depending on different version of the same library.
Q: Can my module add a library JAR to the classpath from outside the IDE installation? For example, I have an application called Etch-a-Kvetch for modeling customer call response systems, and I want to build a module to integrate it into the IDE. The user may already have Etch-a-Kvetch installed on their disk, and I want to reuse the eak.jar main library JAR in my module. It is not present in the IDE's installation directory. Can I add it to the IDE's classpath so my module can use it?
A: Not easily. You have a few options:
Add an entry to ide.cfg. For example:
-cp:a c:\eak\lib\eak.jar
This startup file provides the ability to add classpath entries to the IDE's Java invocation.
Pros: Adds the library as desired. Cons: Very fragile. Assumes that the ide.cfg is actually read, which is not guaranteed for all platforms. Easy to clobber existing user customizations. Dependent on the exact structure of the IDE's bin/ directory, which has changed quite a bit in the past and could change again. Places library in startup classpath, whereas it is preferred to have it in the module classloader only. Must be done before the IDE starts, requiring some kind of manual installation step and making updating your module very difficult.
Duplicate eak.jar in modules/ext/. That is, ship a copy of the required JAR file inside the IDE installation, and continue to refer to dynamic resources in the desired external location.
Pros: Simple to implement and should be reliable. Version of the library shipped can be controlled to match that which the module was compiled against, avoiding potential version skew. Cons: Impractical when the library is physically very large, or there are licensing issues involved in redistributing it. Bugfix upgrades to the master library may not be reflected in the IDE's copy.
Partition your module and use a new classloader. In other words:
logically divide your module into two halves. The first half will form a
compilation unit depending on the Open APIs and will contain all of the
classes referred to directly in the module manifest (the installer, data
loaders, or whatever you have). It should contain one or more interfaces or
similar constructs which describe what it expects the second half to
implement. The second half will form a separate compilation unit, depending
on the first half, possibly the Open APIs, and also eak.jar. It
should contain implementations of the interfaces specified in the first
half. The first half, at install/restore time (or lazily when any
functionality is needed) should create a new URLClassLoader
whose parent should be the first half's classloader, and including as URLs
the locations of both the second half as a JAR and the library JAR; using
this classloader, look up the implementation classes by name; create new
instances of them; cast them to the interface types; and begin using them.
The second half should probably be placed in a separate JAR file; if not, it
will be necessary to subclass the dynamic classloader to not delegate class
loads for the implementation packages to its parent. Either way, it is
strongly recommended that the build process enforce that the first half
compile without reference to the second.
Pros: Compliant with the Open APIs and reliable. The library JAR may be located anywhere at runtime and could even be moved or replaced at runtime. Cons: Potentially complex to implement. Some use of reflection required, though it should be safe. More complex build and test procedure for the module. The partition between the two halves must be carefully chosen, especially for large modules, to minimize the complexity of the interfaces and push as much implementation as possible to one side or the other.
Oyetunde Fadele has kindly posted a detailed explanation of how to use this technique in practice: see his message long ago on<EMAIL_ADDRESS>@FOOTER@