Java Doc for Fiber.java in  » 6.0-JDK-Modules » jax-ws-runtime » com » sun » xml » ws » api » pipe » Java Source Code / Java DocumentationJava Source Code and Java Documentation

JAX-WS RI is capable of running a large number of request/response concurrently by using a relatively small number of threads. This is made possible by utilizing a Fiber — a user-level thread that gets created for each request/response processing.

A fiber remembers where in the pipeline the processing is at, what needs to be executed on the way out (when processing response), and other additional information specific to the execution of a particular request/response.

Suspend/Resume

Fiber can be NextAction.suspend suspended by a Tube . When a fiber is suspended, it will be kept on the side until it is Fiber.resume(Packet) resumed . This allows threads to go execute other runnable fibers, allowing efficient utilization of smaller number of threads.

Context-switch Interception

FiberContextSwitchInterceptor allows Tube s and Adapter s to perform additional processing every time a thread starts running a fiber and stops running it.

Context ClassLoader

Just like thread, a fiber has a context class loader (CCL.) A fiber's CCL becomes the thread's CCL when it's executing the fiber. The original CCL of the thread will be restored when the thread leaves the fiber execution.

Debugging Aid

Because Fiber doesn't keep much in the call stack, and instead use Fiber.conts to store the continuation, debugging fiber related activities could be harder.

Setting the Fiber.LOGGER for FINE would give you basic start/stop/resume/suspend level logging. Using FINER would cause more detailed logging, which includes what tubes are executed in what order and how they behaved.

When you debug the server side, consider setting Fiber.serializeExecution to true, so that execution of fibers are serialized. Debugging a server with more than one running threads is very tricky, and this switch will prevent that. This can be also enabled by setting the system property on. See the source code.
author:
   Kohsuke Kawaguchi
author:
   Jitendra Kotamraju

Fiber may run synchronously for various reasons.

The removal of the interceptor takes effect immediately after the current tube returns from its Tube.processRequest(Packet) or Tube.processResponse(Packet) , before the next tube begins processing.

So when the tubeline consists of X and Y, and when Y uninstalls an interceptor on the way out, then the order of execution will be as follows:

1. Y.processResponse() (notice that this happens with interceptor.execute() in the callstack)
2. interceptor gets uninstalled
3. interceptor.execute() returns
4. X.processResponse()

If a fiber was suspended from the Tube.processRequest(Packet) method, then the execution will be resumed from the corresponding Tube.processResponse(Packet) method with the specified response packet as the parameter.

If a fiber was suspended from the Tube.processResponse(Packet) method, then the execution will be resumed from the next tube's Tube.processResponse(Packet) method with the specified response packet as the parameter.

This method is implemented in a race-free way.

This method blocks and returns only when all the successive Tube s complete their request/response processing.

The newly installed fiber will take effect immediately after the current tube returns from its Tube.processRequest(Packet) or Tube.processResponse(Packet) , before the next tube begins processing.

So when the tubeline consists of X and Y, and when X installs an interceptor, the order of execution will be as follows:

1. X.processRequest()
2. interceptor gets installed
3. interceptor.execute() is invoked
4. Y.processRequest()

This works like Thread.currentThread . This method only works when invoked from Tube .

This method returns null if no packet has been associated with the fiber yet.

Fiber may run synchronously for various reasons. Perhaps this is on client side and application has invoked a synchronous method call. Perhaps this is on server side and we have deployed on a synchronous transport (like servlet.)

When a fiber is run synchronously (IOW by Fiber.runSync(Tube,Packet) ), further invocations to Fiber.runSync(Tube,Packet) can be done without degrading the performance.

So this value can be used as a further optimization hint for advanced Tube s to choose the best strategy to invoke the next Tube . For example, a tube may want to install a FiberContextSwitchInterceptor if running async, yet it might find it faster to do Fiber.runSync(Tube,Packet) if it's already running synchronously.

The removal of the interceptor takes effect immediately after the current tube returns from its Tube.processRequest(Packet) or Tube.processResponse(Packet) , before the next tube begins processing.

So when the tubeline consists of X and Y, and when Y uninstalls an interceptor on the way out, then the order of execution will be as follows:

1. Y.processResponse() (notice that this happens with interceptor.execute() in the callstack)
2. interceptor gets uninstalled
3. interceptor.execute() returns
4. X.processResponse()

If a fiber was suspended from the Tube.processRequest(Packet) method, then the execution will be resumed from the corresponding Tube.processResponse(Packet) method with the specified response packet as the parameter.

If a fiber was suspended from the Tube.processResponse(Packet) method, then the execution will be resumed from the next tube's Tube.processResponse(Packet) method with the specified response packet as the parameter.

This method is implemented in a race-free way. Another thread can invoke this method even before this fiber goes into the suspension mode. So the caller need not worry about synchronizing NextAction.suspend and this method.

This method blocks and returns only when all the successive Tube s complete their request/response processing. This method can be used if a Tube needs to fallback to synchronous processing.

Example:

 class FooTube extends 
AbstractFilterTubeImpl  {
 NextAction processRequest(Packet request) {
 // run everything synchronously and return with the response packet
 return doReturnWith(Fiber.current().runSync(next,request));
 }
 NextAction processResponse(Packet response) {
 // never be invoked
 }
 }
 

This method works like Thread.start .
Parameters:
  tubeline - The first tube of the tubeline that will act on the packet.
Parameters:
  request - The request packet to be passed to startPoint.processRequest().
Parameters:
  completionCallback - The callback to be invoked when the processing is finished and thefinal response packet is available.
See Also:   Fiber.runSync(Tube,Packet)