|
|
|
|
| |
Using WebLogic File Services
This section describes the WebLogic File services and includes the following topics:
Overview of WebLogic File Services
WebLogic File provides high-speed, client-side access to native operating system files on the server. The client API extends the lowest-common-denominator capabilities of Java (java.io.InputStream and java.io.OutputStream), which allows it to be used seamlessly in existing code, with additional services that are specific to manipulating remote files.
As a service, WebLogic File also has access to all of the other WebLogic facilities, like logging, instrumentation, and workspaces. All WebLogic component-based services, including File services, are integrated into the WebLogic framework and can share access and resources. Their APIs share many common aspects that make building a complex networked application easier. Your application may use a variety of these services, all of which can share access to objects and client resources.
With WebLogic File, as with other WebLogic services, the client uses factory methods to generate T3FileInputStream and T3FileOutputStream objects. These classes extend the standard Java InputStream and OutputStream classes, allowing them to be plugged into existing client code. They also provide additional methods that are specific to remote file streams.
WebLogic File enhances read and write performance over a network by transmitting data in buffers whose size is independent of the size of the requests, and by using readAhead and writeBehind buffering. The implementation increases the rate of data transfer in several ways.
An application may specify the transfer buffer size, the number of buffers of read ahead, and the number of buffers of write behind, or it may rely on default values. The default buffer size is 100K, and the default number of buffers for both read ahead and write behind is 1.
The defaults set by WebLogic File are usually the best choice for maximum speed. If you decide not to use the defaults, here are some hints for choosing other values.
This document covers information specific to using the WebLogic File API. You should also read Developing WebLogic Server Applications. If this is your first experience working with InputStream and OutputStream in Java, you may also want to read the information available in the JavaSoft tutorial.
WebLogic File API Reference
The following classes and interfaces make up the weblogic.io.common package.
Package weblogic.io.common
Class java.lang.Object
Interface weblogic.io.common.IOServicesDef
Class java.io.InputStream
Class weblogic.io.common.T3FileInputStream
Class java.io.OutputStream
Class weblogic.io.common.T3FileOutputStream
Interface weblogic.io.common.T3File
Interface weblogic.io.common.T3FileSystem
Class java.lang.Throwable
(implements java.io.Serializable)
Class java.lang.Exception
Class weblogic.common.T3Exception
WebLogic File Objects and Classes
T3ServicesDef t3services;
Hashtable env = new Hashtable();
env.put(Context.PROVIDER_URL, "t3://localhost:7001");
env.put(Context.INITIAL_CONTEXT_FACTORY,
weblogic.jndi.WLInitialContextFactory.class.getName());
Context ctx = new InitialContext(env);
t3services = (T3ServicesDef)
ctx.lookup("weblogic.common.T3Services");
ctx.close();
T3FileSystem myFS = t3services.io().getFileSystem("usr");
T3File myFile = myFS.getFile("myDirectory/myFilename");
T3FileOutputStream t3os = myFile.getFileOutputStream();
t3os.write(b);
Setting Up the WebLogic Server to Read and Write Files
Before you can use WebLogic File services, you must first establish one or more path prefixes -- a fileSystem -- for use by clients. Set the Name and Path attributes for File T3 service in the Administration Console. For example, to map the file system name users to the path on the server host /usr/local/tmp, specify the Name as users and specify the Path as /usr/local/tmp. a
When you request a T3FileSystem from the IOServicesDef factory -- eventually to be used to creating a T3File and reading/writing to it with an input or output stream -- you use the registered fileSystem name as an argument for the getFileSystem() method. The T3FileSystem object that is returned is mapped to the specified fileSystem.
For security reasons, a WebLogic client cannot access files higher in the directory than the lowest directory registered as part of a file system name. Filenames cannot contain dot dot (..) or an Exception is thrown. For example, an attempt to read or write /users/../filename throws an Exception.
Note: When you are setting file attributes on a Windows NT system, you cannot use single backslashes (\) because they are interpreted as escape characters. Using single backslashes when setting a property result in an error message similar to this:
java.io.FileNotFoundException: Remote file name <filename> malformed
You can either use double backslashes, as in this example:
weblogic.io.volume.vol=c:\\remote\\temp
or use forward slashes instead, which are properly mapped to a Window-style syntax by the parser:
weblogic.io.volume.vol=c:/remote/temp
Manufacturing T3File-Related Objects
In these examples, we show how to obtain request the input and output streams necessary to read and write to a remote T3File. We obtain the remote T3File object from a T3FileSystem interface. Here, users is the name of a fileSystem that is specified using the Administration Console. It maps to the absolute path /usr/local/users on the WebLogic Server host.
T3ServicesDef t3services = getT3Services("t3://localhost:7001");
// Get a T3FileSystem object from the IOServicesDef factory
// Give a registered fileSystem as an arg
T3FileSystem myFS = t3services.io().getFileSystem("users");
// Get a T3File from the T3FileSystem
T3File myFile = myFS.getFile("ben/notes");
// Get an OutputStream to write to the file
T3FileOutputStream t3os = myFile.getFileOutputStream();
// Write a byte "b" to the OutputStream
t3os.write(b);
This code creates and writes a byte to a file that maps to the Server host path /usr/local/users/ben/notes.
The method getT3Services() is in class weblogic.common.T3Client. You can add this method to your client.
This brief example illustrates the most common usage. There are other way to request particular T3File-related objects from the IOServicesDef factory, through a set of convenience methods that allow you to directly request a T3FileInputStream or T3FileOutputStream without first creating a T3FileSystem or T3File object.
Here are examples of using the convenience methods provided by the IOServicesDef factory.
You can request a T3FileInputStream or T3FileOutputStream object directly from the IOServicesDef factory by calling the getFileInput/OutputStream() method, with a pathname argument that follows this pattern:
/registeredFileSystem/fileName
where the registeredFileSystem is a mount-point registered in the Administration Console as the Path attribute and the fileName is the name of the destination file.
When you request a T3FileInputStream or T3FileOutputStream object directly, without getting one from methods called on a T3FileSystem, you must include the leading slash in the fileSystem name or the server generates this type of error:
java.io.FileNotFoundException: Remote file name filename is relative
The T3FileInputStream object uses the defaults for buffer size and readAhead. If you choose not to use the default settings for buffer size and readAhead/writeBehind, you can set these values by using different factory methods that allow you to specify these values. In this example, an InputStream object is created with a buffer size of 1024 bytes and 3 readAhead buffers:
int bufferSize = 1024;
int readAhead = 3;
T3ServicesDef t3services = getT3Services("t3://localhost:7001");
InputStream is =
t3services.io().getFileInputStream("/users/myfile",
bufferSize,
readAhead);
In this example, the OutputStream object is created with a buffer of 1024 bytes and 2 writeBehind buffers. For information on getT3Services(), see the javadoc for the T3Services class.
int bufferSize = 1024;
int writeBehind = 2;
T3ServicesDef t3services = getT3Services("t3://localhost:7001");
Outputstream os =
t3services.io().getFileOutputStream("/users/myfile",
bufferSize,
writeBehind);
If an error occurs, the factory methods throw the exception weblogic.common.T3Exception, which contains the cause of the problem as a nested exception.
T3FileSystems and T3Files
The T3FileInputStream Class
public int bufferSize();
public int readAhead();
Currently, T3FileInputStream does not support the following methods: java.io.InputStream.mark() and java.io.InputStream.reset().
The T3FileOutputStream Class
public int bufferSize();
public int writeBehind();
Programming with WebLogic File Services
Here are step-by-step instructions on how to request and use T3File-related objects in your application.
A code example is provided following these steps.
Step 1. Import Packages
In addition to other packages you import for your program, WebLogic File applications import the following:
import java.io.*;
import weblogic.common.*;
import weblogic.io.common.*;
Step 2. Obtain a Remote T3Services Interface
From a WebLogic client application, you access the T3File services via the T3ServicesDef remote factory interface that lives on the WebLogic Server. Your client obtains a remote stub to the T3Services object via a JNDI look-up. We define and list a method called getT3Services() that you can add to you client to access the T3Services stub. For information on getT3Services(), see the javadoc for the T3Services class.
You can simply call the method giving the URL of the WebLogic Server as an argument as follows:
T3ServicesDef t3services = getT3Services("t3://weblogicurl:7001")
Step 3. Create a T3FileSystem and a T3File
In general, perform the following steps to begin working with reading and writing files:
Use the T3ServicesDef remote interface to access the IOServices factory. Call the IOServices factory method getFileSystem() to get a T3FileSystem object. Supply the name of a file system that is registered on the WebLogic Server as an argument. You register a file system using the Administration Console.
For this example, we assume the following file system property is configured with a name of myFS and a path of /usr/local.
T3Files created in the T3FileSystem mapped to myFS are physically located in the directory /usr/local on the WebLogic Server's host. Here is the code to get the T3FileSystem and a T3File named test:
T3FileSystem t3fs =
t3services.io().getFileSystem("myFS");
T3File myFile = t3fs.getFile("test");
We can also check to see if the file exists before we read from or write to it, as shown here:
if (myFile.exists()) {
System.out.println("The file already exists");
}
else {
// Create a file with an array of bytes. We'll write it
// to an output stream in the next step
byte b[] = new byte[11];
b[0]='H'; b[1]='e'; b[2]='l'; b[3]='l'; b[4]='o'; b[5]=' ';
b[6]='W'; b[7]='o'; b[8]='r'; b[9]='l'; b[10]='d';
}
Step 4. Create and Use an OutputStream Object
We have assembled an array of bytes that we'd like to write to a T3File on the WebLogic Server. You customarily create a T3File, and then request an OutputStream to write to it, using the T3File.getOutputStream() method.
Using the T3File myFile that we created in the previous step, this example illustrates this process:
Outputstream os =
myFile.getFileOutputStream();
os.write(b);
os.close();
Always close the OutputStream object when work with it is completed.
Step 5. Create and Use an InputStream Object
Now we have got a T3File that we'd like to read from and confirm its contents. You request and use an InputStream object with the same patterns you use for an OutputStream object.
Here we request an InputStream object with which we can read from the T3File myFile. This opens an InputStream to the T3File. In this example, we're reading bytes; first, we allocate an array of bytes to read into. This array is later used to create a String that can be displayed. Then, we use the standard methods of the java.io.InputStream class to read from the T3File, as shown here:
byte b[] = new byte[11];
InputStream is = myFile.getFileInputStream();
is.read(b);
is.close();
Now let's create a String for display to confirm the results:
String result = new String(b);
System.out.println("Read from file " + T3File.getName()
" on the WebLogic Server:");
System.out.println(result);
is.close();
Always close the InputStream object when work with it is completed.
Code Example
The full code example is a runnable example that we ship in the examples/io directory in the distribution. You can compile and run the example using the instructions located in the same directory. The example uses a main() method so that you can run the example from the command line.
public class HelloWorld {
public static void main(String[] argv) {
// Strings for the WebLogic Server URL, the T3FileSystem
// name, and the T3File name
String url;
String fileSystemName;
String fileName;
// Check the user's input, and then use it if correct
if (argv.length == 2) {
url = argv[0];
// Use the local file system on the client
fileSystemName = "";
fileName = argv[1];
}
else if (argv.length == 3) {
url = argv[0];
fileSystemName = argv[1];
fileName = argv[2];
}
else {
System.out.println("Usage: java example.io.HelloWorld " +
"WebLogicURL fileSystemName fileName");
System.out.println("Example: java example.io.HelloWorld " +
"t3://localhost:7001 users test");
return;
}
// Obtain remote T3Services factory from WebLogic Server
try {
T3Services t3services = getT3Services(url);
// Get the file system and the file
System.out.println("Getting the file system " + fileSystemName);
T3FileSystem fileSystem =
t3services.io().getFileSystem(fileSystemName);
System.out.println("Getting the file " + fileName);
T3File file = fileSystem.getFile(fileName);
if (file.exists()) {
// The file exists. Don't do anything
System.out.println("The file already exists");
}
else {
// The file does not exist. Create it.
byte b[] = new byte[11];
b[0]='H'; b[1]='e'; b[2]='l'; b[3]='l'; b[4]='o'; b[5]=' ';
b[6]='W'; b[7]='o'; b[8]='r'; b[9]='l'; b[10]='d';
// Get an OutputStream and write to the file
System.out.println("Writing to the file");
OutputStream os = file.getFileOutputStream();
os.write(b);
os.close();
}
// Get an InputStream and read from the file
byte b[] = new byte[11];
System.out.println("Reading from the file");
InputStream is = file.getFileInputStream();
is.read(b);
is.close();
// Report the result
String result = new String(b);
System.out.println("File contents is: " + result);
}
catch (Exception e) {
System.out.println("The following exception occurred " +
"while running the HelloWorld example.");
e.printStackTrace();
if (!fileSystemName.equals("")) {
System.out.println("Make sure the WebLogic server at " +
url + " was started with " +
"the property weblogic.io.fileSystem." +
fileSystemName + " set.");
}
}
}
private static T3ServicesDef getT3Services(String wlUrl)
throws javax.naming.NamingException
{
T3ServicesDef t3s;
Hashtable env = new Hashtable();
env.put(Context.PROVIDER_URL, wlUrl);
env.put(Context.INITIAL_CONTEXT_FACTORY,
weblogic.jndi.WLInitialContextFactory.class.getName());
Context ctx = new InitialContext(env);
t3s = (T3ServicesDef) ctx.lookup("weblogic.common.T3Services");
ctx.close();
return(t3s);
}
}
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|