Using the Publish Wizard

 

This section discusses how to use the Publish Wizard, including the following topics:

• Starting the Publish Wizard

• Creating a ZAC Package

• Publishing a ZAC Package

• Using the command line Publish Utility

• Connecting the Publish Wizard to Other Servers

• Updating a Published ZAC Package

• Importing a Published ZAC Package from Another Server

• Removing a Published ZAC Package

• Creating an Installer/Bootstrap Application

• Packaging a JRE

 

---

Starting the Publish Wizard

If you wish to publish to a WebLogic Server, that server must be running, you must have configured a DefaultWebApp for the server, and you will need to know a user and password that has permission to publish. For more details, see Publishing a ZAC package. However, you can create and inspect existing ZAC packages without any Servers running.

Users can start the Publish Wizard from the command line (after setting your CLASSPATH with this command:

 $ java weblogic.drp.admin.PublishWizard

The ZAC Publish Wizard splash screen will appear while ZAC starts up, then the main dialog for the Publish Wizard will appear:

Figure 2-1 The ZAC Publish Wizard Main Window

 

 

---

Creating a ZAC Package

You use the ZAC Publish Wizard to create new ZAC packages, import existing packages from other servers, or update previously published packages. A ZAC package may be an application, applet, or library.

The Publish Wizard will guide you through the process of creating a new package or republishing an existing. You can also use ZAC's "test run" option, which allows you to try running your ZAC application to check that it will run as configured.

1. From the Package menu, select New to create a new package, or Open to view or edit an existing package. Alternatively, you can double-click on an existing package. This will open the Package panel.

2. On the Package panel, select a package type. You may publish an applet, a Java application, or a class library as a ZAC package. Typically, you publish libraries as a component that other published applications depend upon.

   Figure 2-2 Publishing a New Library Package

   
    

3. Name the package. This will not be a public display name; it will be used for filename purposes, so make it short and easy to identify. Note: You may not use spaces in the package name.

   Figure 2-3 Naming the Package

   
    

4. Supply a title for the package and a short prose description of it. Both will be used for display purposes.

   Figure 2-4 Supplying a Title and Description

   
    

5. Set the version number.

   Figure 2-5 Setting the Version Number

   
    

6. Browse to the directory that contains the files for the ZAC package. Everything in the directory you choose, plus everything in all its subdirectories, will be published.

   You can exclude files from the published package by adding to the list of file types to be ignored. This allows you to locate files that may be used to generate the package in the same directory, without publishing them. In general, you will always want to ignore index.xml and index.osd files, which are specific to each client. A list of suggested files to exclude is supplied; you can add to or delete from this list for your published package.

   Figure 2-6 Choosing the Top-Level Directory of the Package

   
   Find a GIF image to use as a thumbnail for the package. The image should be 32x32 pixels with a transparent background for best results.
    

7. Find a GIF image to use as a thumbnail for the package. The image should be 32x32 pixels with a transparent background for best results.

   Figure 2-7 Supplying a Thumbnail Image

   
    

8. If you are publishing an applet, you will be asked to enter the applet's main class, the CODEBASE, and a list of applet parameters that would customarily be listed in PARAM tags. If the applet is online, you can enter a URL that ZAC will use to find the applet and complete the list of parameters automatically. To identify the applet, supply:

   The main classname

   If you enter a URL for an online location of the applet (along with the document base), ZAC will find the applet and supply its parameter list automatically.

   The document base

   This is the URL of the webserver that is hosting the applet. Supplying the document base and the name of the class is enough information for ZAC to find an online running version of the applet and load the parameter list automatically.

   The CODEBASE attribute

   This is a URL where the applet may retrieve additional class files as required. It is a common practice to set this to http://yourserver:port/classes where yourserver is your WebLogic Server and you have registered the ClasspathServlet against the virtual name classes. For more details see the Administrators Guide on Registering the WebLogic servlets.

   The applet parameters

   Applet parameters are a list of name=value pairs that supply initialization and runtime variables to the applet, analogous to those supplied between the <APPLET> tags in an HTML file.

   Figure 2-8 Specifying Applet Parameters

   
    

9. Enter the path to the appropriate class for the published package. If you are publishing an application, you will be asked to enter the full path to the Java class that contains the main() method that starts the application. You may also enter any initialization arguments, required by the main() method, in the Parameters text area.

   Figure 2-9 Locating the Class to Start the Application

   
    

   Specify the CLASSPATH for your package (Required). If all of the necessary classes are contained in the published package itself, you can simply specify a dot "." for the current directory. The CLASSPATH is always relative to the top-level directory for the application. If you are publishing an application, the class that contains the main() method to run your application must be in the CLASSPATH of the package.

   When publishing any type of package, CLASSPATH entries are always relative to the top of the local directory being published. For example, when publishing the local directory c:\myapps—which contains the following—

     c:\myapps\classes\foo\Main.class
     c:\myapps\bundle1.jar
     c:\myapps\lib\bundle2.jar
   

   where the class foo.Main is contained in the package foo—you would set the CLASSPATH for the package as:

     classes;bundle1.jar;lib\bundle2.jar
   

   Figure 2-10 Specifying the Package CLASSPATH

   
    

10. Here, you may specify Java system properties that your application requires. List one name=value pair per line.

    Figure 2-11 Specifying Java System Properties

    
     

11. Next, you may set up dependencies for your package upon other packages. ZAC will ensure those packages are installed and up-to-date on the client machine also. You must make ZAC packages of shared libraries or other applications that your package depends upon, and specify the dependencies using package names.

    Using dependencies with ZAC allows several different applications to share common code on the client machine. When common code is updated, it is consequently updated for all dependent ZAC applications.

    For example, if you were developing applications that depend upon the WebLogic and the Swing classes as libraries, you could list these as dependencies for each application, and there need only be a single copy of those libraries on the client machine.

    Figure 2-12 Setting up Dependencies

    
     

    Locate a published package from an available WebLogic Server in the left hand window and click 'Add'. Details about the depended-upon package are displayed in the right hand window. To remove a depended-upon package, select it in the right hand window, and click on 'Remove'.

 

---

Publishing a ZAC Package

Once you have created a new package or updated details for a package that you have published previously, you are ready to publish the package to a WebLogic Server.

1. Select the package you wish to publish in the ZAC Publish Wizard main window. In the "Package" menu, select "Publish" if it is enabled. If you have multiple WebLogic Servers listed in the 'WebLogic Servers' panel, the second option "Publish to" will be enabled, which allows you to select the WebLogic Server to publish to.

   If you select "Publish" the WebLogic Server is automatically chosen for you. This will be either the only server listed, or the last server that you published to or reverted from.

   If you select "Publish to", you will need to select the address/port of the WebLogic Server to which you want to publish this package.

2. The first time you publish to a WebLogic Server, and each time you publish after you have restarted ZAC, you will be asked to supply a name and password. To publish, you must supply a username and password for the T3User that has "write" permission for the ACL weblogic.zac in the weblogic.properties file. If unset, this ACL defaults to granting only the "system" user with write (publish) privileges.

   Figure 2-13 Supplying Authorization for Publishing

   
    

3. The progress of the publishing operation is shown in the "Publishing..." window. When complete, press "Close", or "Details >>" to review the details of the published package.

   Figure 2-14 The Publishing Progress Dialog

   
    

Reverting a ZAC Package

If you make changes to a local ZAC package before publishing it, you may revert the package to a version previously published on a WebLogic Server. Select the local package, and choose "Revert", or "Revert from" in the "Package" menu. If you are running more than one server you will need to select the later option in order to choose the server to revert from. If you choose "Revert", the server is chosen for you as either the only server that is listed, or the last server that you published to or reverted from.

 

---

Using the command line Publish Utility

You can use the command line Publish Utility to publish a ZAC package on the WebLogic Server, as an alternative to using the ZAC Publish Wizard. The Publish Utility is a stand alone java application that you may run from the command line, or invoke from a shell script. You configure the actions of the Publish Utility by supplying command line options. These options closely follow the parameters that you define in the ZAC Publish Wizard. Use the Publish Utility on the command line as follows:

  $ java weblogic.drp.admin.Publish [options]

-name zacPackage

(Required) The name for the ZAC package you are publishing, as it shall appear on the WebLogic Server. Note that the name should not contain any spaces.

-dir packageDir

(Required) The pathname of the top-level local directory that contains the entire contents for the ZAC package that you are creating and publishing. The contents of the directory, and all subdirectories are included in the new package.

-host hostname

(Optional) The host name of the WebLogic Server you are publishing to. This defaults to "localhost".

-port portnumber

(Optional) The port number of the WebLogic Server you are publishing to. This defaults to "7001".

-login username -password passwd

(Optional) You must specify a username and password to publish a package on a WebLogic Server that uses security controls for publish authentication. By default, this is set to the system user and password by the WebLogic Server. You may grant publish (write) privileges to a user or group by specifying an ACL in the weblogic.properties file. See Setting up WebLogic for Publishing with ZAC (step 2) for details.

By default, the Publish Utility will attempt to publish the package without using a username and password. This will fail unless ZAC publish write privileges have been granted to everyone.

-verbose | -v

Causes the Publish Utility to print verbose messages about its operation.

-help

Prints a short summary of usage for the Publish Utility.

 

---

Connecting the Publish Wizard to Other Servers

When you start the Publish Wizard, it will connect automatically to the WebLogic Server running at the default location, and display it in the lower window pane. To discover other WebLogic Servers, select "Add" from the "server" menu to access the following dialog.

Figure 2-15 The Add Server dialog

 

 

---

Updating a Published ZAC Package

Updating a previously published application is simple.

1. Start the Publish Wizard.

2. Select the package you want to update

3. Select "Open" from the "Package" menu.

4. Carry out the same steps as for creating and publishing a new package.

 

---

Importing a Published ZAC Package from Another Server

You can import a published package from one WebLogic Server and publish it on another WebLogic Server. At that point, the package becomes a separate copy at will not be updated if the original package is updated.

To import a published package:

1. Add the WebLogic Server host you wish to import from to the Publish Wizard's host list. See Connecting the Publish Wizard to Other Servers.

2. Select the published package in the other WebLogic Server host.

3. Select "import" from the "Package" menu.

4. You will be asked where you wish to store the imported ZAC package files. Select an appropriate directory, and enter a directory name in the text box. A new directory will be created under that name in the current directory you have browsed to. If you do not specify a name, the operation will not be successful.

   Figure 2-16 Storing the ZAC Packaged Files

   
    

5. Next, you are prompted for a name to save the ZAC package definition under. This should be saved in the default directory where you keep your ZAC package definitions. This is usually saved under the directory /weblogic_publish.

   Figure 2-17 Saving the ZAC Package Definition

   
    

6. The imported package will apper under the "local package" list, under the name it was published with on the originating server.

7. You may now publish the package, as described under Publishing a ZAC Package.

 

---

Removing a Published ZAC Package

The remove operation only removes the published application files themselves, including directory for the package that is stored in a package directory in the ZAC publish root.

Removing a package does not affect the WebLogic Server or the original files from which the package was published, nor will it remove local files from a ZAC client.

1. From the Server menu, choose Remove package.

2. Browse the WebLogic Server from which the package is to be removed.

3. Select the package and press the Choose button.

 

---

Creating an Installer/Bootstrap Application

You can also use the ZAC Publish Wizard to create a set of native programs — an installer and a bootstrap — for various operating systems that become part of a published Java application.

The installer program is a native executable that installs your published Java program on the local machine; it may also install a JRE. It doesn't require a Java environment itself, so it can run out-of-the-box in the native OS. It's a little like an InstallShield for Java.

The bootstrap is also a native program; the user runs the bootstrap to invoke the published application. The bootstrap takes care of monitoring for updates, downloading and updating the user's application, and other administrative ZAC functions.

Installer/bootstrap programs can be created for the following OS types:

• Win32 (Windows95/98 and Windows NT)

• Solaris/SPARC

• Linux/x86

• DECUnix/Alpha

• HPUX (HPUX 11)

Both the installer and the bootstrapper are small native, applications. You will need to create these for each type of operating system and CPU type that you expect your clients will use.

To create the installer/bootstrap executables in the Publish Wizard:

1. Start the Publish Wizard, and highlight the ZAC package for which you wish to create a bootstrapper installation program. You must have previously created a ZAC package for your application and published it on the WebLogic Server.

2. Select Create bootstrap app... from the Package menu.

3. Set the appropriate operating system and CPU type for this application. Choosing an OS and CPU will set some default values that you can adjust as necessary.

   Figure 2-18 Setting OS Details for the Bootstrap

   
    

4. Enter the host and port of the publishing WebLogic Server. If you are preparing a bootstrapper application for a package installed on another server, you can find the available servers by pressing the Browse button.

   Figure 2-19 Identifying the Publishing WebLogic Server

   
    

5. Assign a name for the native bootstrapper executable. The bootstrapping process creates two applications: the installer package (usually very small) that the client downloads and runs initially, and the bootstrap that the user uses to invoke the published application each time he runs it. What you name in this step is the bootstrapper executable.

   Figure 2-20 Assigning a Name

   
    

6. Select one or more methods for finding and choosing a Java environment. You may depend on a locally available copy of the Microsoft or JavaSoft JVM, or you can load a JRE (Java Runtime Environment) that has been published as a ZAC package. Check the options that you want to be available to the client, and then order how those options should be processed by using the up-and-down arrows to the right.

   Figure 2-21 Making the JRE Available to the Client Application

   
    

7. If you selected Load own JRE, you will be prompted to locate the publishing WebLogic Server where the installer can find a published package of the JRE. For details on packaging your own JRE with ZAC, see the section Packaging a JRE later in this document.

8. Specify options for the Sun VM memory flags when if is initiated by the bootstrap application. The default values are specified here. You should set them accordingly if you application has special needs.

   Figure 2-22 Setting Memory Options for the Sun VM

   
    

9. Enter the local directory on the client machine into which the bootstrap application should be installed when the user double-clicks the .exe file. The directory will be absolute if you begin the path with a slash (forward or backward depending upon the operating system for which you are publishing this bootstrap). If you choose the Start app in install directory option, the directory selected here is where the application will start from.

   Figure 2-23 Setting a Local Client Directory

   
    

10. Set the client permissions for the files associated with this package.

    Figure 2-24 Setting Access Permissions for Client Files

    
     

11. If you are publishing for Windows, you will be asked to choose some special settings for Windows. You can install shortcuts for the Windows Start menu or desktop and you can set an icon for the bootstrapper package.

    Figure 2-25 Setting Windows-Specific Options

    
     

12. Specify the behavior of the ZAC installation-bootstrap and the post-installation bootstrap. These options are defined as follows:

Update application

If this option is checked, the bootstrap executable will check for newly published versions of the ZAC application and update it if necessary. You may wish to disable this feature if one of these conditions is true:

• You wish the client to run the application offline

• You have embedded ZAC update functionality directly into the application using the ZAC API

• You plan to generate another bootstrap executable for the purpose of updating the ZAC application (See Launch application option below)

Check all dependencies

If this option is checked, the bootstrap executable will check for newly published versions of the ZAC packages that this application depends upon. You may wish to disable this feature for similar reasons to those listed above.

Show progress window

If this option is checked, the bootstrap executable will display a meter indicating the progress of the download when the application updates. If you wish the update to be silent, you can uncheck this option.

Launch application

This option is usually checked. If this option is not checked, then the bootstrap executable will not launch the application. You might uncheck this option to create a bootstrap that will only update the application on the client machine. You could use such a bootstrap in conjunction with a bootstrap that only starts the application and does not update it.

Figure 2-26 Setting up Bootstrapper Options

 

1. Set a WebLogic username and password for access to this package. This should correspond to a WebLogic user that is on the access control list (ACL) for read permission to this application on the publishing WebLogic Server. Note that if you do not set an ACL for a published package, the permission to read defaults to the special group everyone and the permission to write (publish) the package defaults to the special administrative user system. That means that anyone can download your published package, but only a system-level user can publish or republish packages.

   Figure 2-27 Setting the User and Password for Secure ZAC Packages

   
    

2. If you expect your users to access the internet from behind a firewall, you should configure the bootstrap to ask for an HTTP proxy server through which it may access the WebLogic Server. It is a good idea to always leave this option checked, unless you know that your clients are not behind a firewall.

   Figure 2-28 Configuring the Bootstrapper to Prompt for HTTP Proxy Details

   
    

3. Set the debug mode and verbosity of the application. This is useful while you are testing the deployment of your ZAC application from a client machine.

   Figure 2-29 Setting Debug Mode

   
    

4. Review the bootstrap settings. Press the Generate button when completed.

   Figure 2-30 Confirming Your Choices

   
    

5. From the Save As... window, select the location and name of the installation executable. The default name is based on the ZAC package name and the target OS; but you may call this executable file anything you like. You will deploy this executable to clients to install your application.

   Figure 2-31 Saving the Generated ZAC Installation Program

   
    

 

---

Packaging a JRE

You can wrap the entire JRE in a ZAC package and include it with your ZAC application. Including the JRE means that you do not need to make any assumptions about the end user's machine and you are assured that everything necessary for your application is provided, including the correct version of Java. The downside is that the initial download package is larger, and it may install the JRE even though there being another JRE present. This small initial inconvenience may be more desirable than causing installation problems for the user.

Before You Begin

The following steps describe how you should make a ZAC package of theJRE. You can then include this ZAC package as a dependency of yourapplication. Before you start the Publish Wizard, you should do thefollowing:

1. Download the JRE install-shield. The JRE from JavaSoft can be downloaded from JavaSoft.

2. Install it on your development machine. In these instructions, we'll assume you have installed it in the directory c:\jre117.

Now start the Publish Wizard and continue the process.

Creating and Publishing a ZAC JRE Package.

1. Create the package type as "Library" and give it CLASSPATH "." (CLASSPATH doesn't matter in this case). Give it no dependencies.

2. Create a new package for the JRE. We recommend that you choose a name that reflects the OS and CPU type; for example, "JRE_117_win32_x86".

3. Enter a title and description for the JRE package. You can enter any title you wish.

4. Enter the package version as closely to the JRE version as possible. For example,

   For JRE 1.1.7 enter '1' '1' '7'

   For JRE 1.2.0 enter '1' '2' '0'

Entering the correct JRE version is important since the version string is used to determine the default local installation directory for the JRE. Using the same version number as the JRE version will minimize the chance that two separate ZAC packages will overwrite each other's JREs with incompatible versions. Of course, this is only used to determine the default install directory; the user ultimately decides where the JRE shall be installed.

1. You may optionally select a thumbnail image for the package.

2. Specify the top-level directory where you have previously installed the JRE. (In this example, we're using c:\jre117.)

3. Specify simply . (dot) as the CLASSPATH for your library.

4. Skip the other dialog screens and publish the package. Make sure that the publishing server is running before you try to publish.

After the publishing step is complete, you should see the new ZAC JRE package appear in the 'ZAC Publish Wizard' window.

Specifying a Published JRE Package for an Application

Now that you have created your own JRE ZAC package (see section above), you need to add a dependency between it and your ZAC application. Here is how:

1. In the Publish Wizard, create an installer/bootstrap executable for your application, using the instructions in this document in the section Creating an Installer/Bootstrap Application.

1. During the create process, when you make choices on how to configure the Java Environment, you will see three choices that show the preference for choosing a JRE on the client user's host. You can order, select, or deselect these choices as illustrated on the right. Select Load own JRE as one of your VM choices and adjust its position in the preference list using the arrow buttons; then press the Next button.

2. When the bootstrap wizard asks where the JRE is published, provide the following:

   • The hostname and port for the WebLogic Server where you published the ZAC JRE

   • The ZAC name (e.g., "JRE_117_win32_x86") under which the JRE distribution is published

     You can type in the path or Browse for the published package on the appropriate server in your server list.

     Figure 2-32 Locating a Published JRE

     
      

3. Press the Generate button, or proceed to the end of the bootstrap wizard.

4. Finally, choose a file name and path to save the installation executable on the publishing server. For example, \weblogic\public_html\MyAppInstall.exe saves the installer/bootstrapper into the default document root of a WebLogic Server host, where you can publish access to it from an HTML page.

   The native installer will be small, probably about 250 KB for a Windows architecture. You can distribute it to clients however you like; for example, put a link to it on a web page, or attach it to an email.

Debugging and Testing a Published Application

The WebLogic distribution contains native executables for running the ZAC bootstrap from the command line for Win32, Solaris, Linux, and DECUnix. The Windows version (zac.exe) is located in the bin/ directory; the non-Windows versions are located in the lib/{arch}/zac_{arch}/ directories. Each executable also has an _g version that can be used for verbose debugging.

Use the appropriate version of the command line bootstrapper to install or run a ZAC package. For example, you run the Windows version as shown here:

 $ zac.exe -name zacPackage options

The options are defined as follows:

-name zacPackage

Required. The name of the application to launch or download. For example:

 $ zac.exe -name ETrader

-host hostname

Hostname of the publishing WebLogic Server. This defaults to localhost. For example:

 $ zac.exe -name ETrader -host zac.weblogic.com

-port port

Port at which the publishing WebLogic Server is listening for login requests. Defaults to 7001. For example:

 $ zac.exe -name ETrader -host zac.weblogic.com -port 80

-proxy

Prompts for proxy information, according to the configuration set in the ZAC bootstrap wizard when the package was published.

-dir localDir

The local (client) directory where the ZAC application files are located. This defaults to the current working directory. The following example launches a ZAC application called ETrader:

 $ zac.exe -name ETrader -dir /usr/local/zac/

For this example, all files for the ETrader application and all of its dependencies will be stored in the subdirectories below /usr/local/zac/. The actual ZAC application ETrader is stored beneath this directory in another directory with the same name as the package, that is /usr/local/zac/ETrader/. The ZAC bootstrapper looks inside this directory for the OSD application manifest (index.osd).

-root

Start the Java ZAC application in the ZAC root directory. The default it to start the ZAC application in the current working directory.

-vm JVM type

Specifies the order of preference for locating a JVM on the client's machine. Specify any combination of the characters "S","M",or "O" where the highest preference is on the left, and the characters represent:

• S (Sun Java VM)

• M (Microsoft VM)

• O (Own VM. You provide your own JVM as a published ZAC package.)

If you use "O" in this argument, you must specify a JRE with the -jre flag.

-jre zacPackage

Required if you use "O" as an option for the -vm flag. Specifies a ZAC-published JRE.

-Dname=value

Specifies one or more Java system property to the Java VM when it is invoked by the bootstrapper.

—option

Pass the flag "-option" (with a single hyphen) to the Java application as it starts up.

-msnumber

Sets the JVM initial heap size for your client application (in megabytes).

-mxnumber

Sets the JVM maximum heap size for your client application (in megabytes).

-nolaunch

Updates a ZAC package without launching it.

-noquery

Disables the dialog that prompts the user for an alternate installation directory when the bootstrapper is run. By default this is enabled.

-noprogress

Disables the display of the download progress meter.

-noupdate

Launches a ZAC application without attempting to update it. Requires a previously successful download.

-verbose

Enables verbosity for classloading in the Sun JVM. This can be useful for tracking down problems with missing class dependencies on the client.

-help

View a list of the available options. Each option also has a shorthand version; These are indicated in the output of the -help command.