com.ibm.as400.access

Class JavaApplicationCall

  • All Implemented Interfaces:
    Serializable


    public class JavaApplicationCall
    extends Object
    implements Serializable

    Provides an easy way to run Java applications on the IBM i system's Java Virtual Machine from a client. The client Java program specifies the environment, the program to run, and the program parameters. The program then runs on the IBM i system's Java Virtual Machine. Text-based input/output is provided by JavaApplicationCall. Input can be sent to the Java program which will receive the input via standard input (stdin). Standard output (stdout) and standard error (stderr) text generated by the Java program are received by JavaApplicationCall and made available to the calling program. JavaApplicationCall does not support displaying the graphical user interface of the IBM i system's Java program on the client. Other Java facilities, such as remote AWT must be used to display graphical interfaces on the client.

    Sockets are used to send stdin, stdout and stderr between client and IBM i system. The port used can be set via setPort(). The default port sequence is 2850, 2851 and 2852. If the port is in use, this class searches for available ports if findPort is true. stdin, stdout and stderr are not transported across a secure connection even when the rest of the Toolbox is using SSL.

    Note: The presence of a firewall, in either direction between the IBM i system and the client, may prevent JavaApplicationCall from opening the necessary additional ports (for stdin, stdout, and stderr). The administrator may need to authenticate the application through the firewall in both directions: From client to IBM i system; and from IBM i system to client.

    For example, suppose the Java class HelloWorld resides in directory /javatest on the system. The following calls this program and receives program output written to stdout and stderr.

     import com.ibm.as400.access.*;
    
     public class test implements Runnable
     {
        JavaApplicationCall jaCall;
    
        public static void main(String[] args)
        {
           test me = new test();
           me.Main(args);
        }
    
    
        void Main(String[] args)
        {
    
           try
           {
               // The IBM i system where the Java program to run, is located.
               AS400 as400 = new AS400();
    
               // Construct a JavaApplicationCall object.
               jaCall = new JavaApplicationCall(as400);
    
               // Set the name of the Java application to be run.
               jaCall.setJavaApplication("HelloWorld");
    
               // Set the classpath environment variable used by the IBM i system's
               // JVM so it can find the class to run.
               jaCall.setClassPath("/javatest");
    
               // Start the thread that will receive stdout
               Thread outputThread = new Thread(this);
               outputThread.start();
    
               // Start the program.  The call to run() will not return
               // until the IBM i system Java program completes.  If the Toolbox
               // cannot start the Java program, false is returned with
               // a list of AS400Message objects indicating why the program
               // could not start.
               if (jaCall.run() != true)
               {
                    AS400Message[] messageList = jaCall.getMessageList();
                    for (int msg = 0; msg < messageList.length; msg++)
                        System.out.println(messageList[msg].toString());
               }
           }
           catch (Exception e) { e.printStackTrace(); }
    
           System.exit(0);
        }
    
        // This thread will get the output from the IBM i system Java program,
        // and print it.  Note the call to sleep().
        // The getXxxString() methods return immediately even if there is no data.
        public void run()
        {
            while (true)
            {
               String stdOut = jaCall.getStandardOutString();
               if (stdOut != null)
                 System.out.println(stdOut);
    
               String stdErr = jaCall.getStandardErrorString();
               if (stdErr != null)
                 System.out.println(stdErr);
    
               try { Thread.sleep(100); } catch (Exception e) {}
            }
        }
     }
    
    
     
    See Also:
    Serialized Form
    • Constructor Detail

      • JavaApplicationCall

        public JavaApplicationCall()
        Constructs a JavaApplicationCall object.
      • JavaApplicationCall

        public JavaApplicationCall(AS400 system)
        Constructs a JavaApplicationCall object. The Java program is on an IBM i system.
        Parameters:
        system - The system on which contains the Java program.
      • JavaApplicationCall

        public JavaApplicationCall(AS400 system,
                           String application)
        Constructs a JavaApplicationCall object. The Java program is namee application and runs on system system.
        Parameters:
        system - The system on which contains the Java program.
        application - The name of Java program.
      • JavaApplicationCall

        public JavaApplicationCall(AS400 system,
                           String application,
                           String classPath)
        Constructs a JavaApplicationCall object. The Java program is named application and runs on system system. classPath is passed to the system as the value of the CLASSPATH environment variable.
        Parameters:
        system - The system on which contains the Java program.
        application - The name of Java program.
        classPath - The value of the environment variable CLASSPATH.

    • Method Detail

      • getClassPath

        public String getClassPath()
        Returns the value of the CLASSPATH environment variable when running the Java program. Use the forward slash to separate path elements and a colon to separate the elements of CLASSPATH. For example, /dir1:/dir1/dir2/myClasses.jar.

        Valid values are:

        • *ENVVAR No setting is sent from the client to the IBM i system so the IBM i system's default value of CLASSPATH is used.
        • string The value that is set before the program is run.
        Returns:
        The value of CLASSPATH.
      • getCommandCall

        public CommandCall getCommandCall()
        Returns the CommandCall object that was used in the most recent invocation of run().
        Returns:
        The CommandCall object; null if run() has not been called.
      • getDefaultPort

        public int getDefaultPort()
        Returns the default port used to transfer stdin, stdout, and stderr between the client and the IBM i system. Three ports are used. The port returned by this method is used for stdin; (port + 1) is used for stdout; and (port + 2) is used for stderr. If not otherwise specified, the default port is 2850.
        Returns:
        The default port.
      • getGarbageCollectionFrequency

        public int getGarbageCollectionFrequency()
        Returns the relative frequency that garbage collection runs. This value applies only to OS/400 V4R2 and V4R3. It is ignored in V4R4 and later versions.
        Returns:
        The relative frequency.
      • getGarbageCollectionInitialSize

        public int getGarbageCollectionInitialSize()
        Returns the initial size, in kilobytes, of the garbage collection heap. A large size can keep the garbage collector from starting when the Java program is small, improving performance.

        Possible values are:

        • 2048 The default initial size is 2048 kilobytes.
        • heapSize The initial value of the garbage collection heap in kilobytes. We recommend the initial heap size be 2048 kilobytes (the default) or larger.
        Returns:
        The initial size of the garbage collection heap.
      • getGarbageCollectionMaximumSize

        public String getGarbageCollectionMaximumSize()
        Returns the maximum size, in kilobytes, that the garbage collection heap can grow to. This value is used to prevent runaway programs from consuming all available storage.

        Possible values are:

        • *NOMAX The default maximum size is not specified by the user. The maximum is determined by the system. The heap will grow until all system resources are depleted. Then a synchronous garbage collection is started to reclaim resources no longer in use.
        • heapSize The value in kilobytes that the garbage collection heap can grow to.
        Returns:
        The maximum size that the garbage collection heap can grow to.
      • getGarbageCollectionPriority

        public int getGarbageCollectionPriority()
        Returns the priority of the tasks running garbage collection. This value applies only to OS/400 V4R2 and V4R3. It is ignored in V4R4 and later versions.
        Returns:
        The priority of the tasks.
      • getInterpret

        public String getInterpret()
        Returns whether all Java class files should be run interpretively.

        Possible values are:

        • *OPTIMIZE Whether all Java classes are run interpretively depends on the value of the optimize property. If optimize is *INTERPRET, all Java classes will be run interpretively. If any other value was specified for optimize, only Java classes with Java programs created using CRTJVAPGM command and specifying OPTIMIZE(*INTERPRET) will be run interpretively.
        • *NO Only Java classes with Java programs created using CRTJVAPGM command and specifying OPTIMIZE(*INTERPRET) will be run interpretively. Java classes that need a Java program created will be created with the optimization level specified in the optimize property.
        • *YES All Java classes will be run interpretively regardless of the OPTIMIZE value associated Java program. Java classes that need a Java program created will use the optimization level specified in the optimize property.
        Returns:
        Whether all Java class files should be run interpretively.
      • getJavaApplication

        public String getJavaApplication()
        Returns the name of Java application to be run. If the Java application is not be set, null is returned.
        Returns:
        The name of Java application.
      • getJobName

        public String getJobName()
        Returns the name that this job will run under. The maximum length returned is 10 characters.

        Possible values are:

        • QJVACMDSRV - The default job name.
        • *GEN - The job name will be generated from the class name.
        • string - Any generic string value.
        Returns:
        The value of the job name.
        Since:
        i5/OS V5R3M0
      • getMessageList

        public AS400Message[] getMessageList()
        Returns the list of IBM i system messages generated if the Java program cannot be started. Before run() is called and if the Java program can be started, an empty list is returned.
        Returns:
        The array of AS400Message objects.
      • getOptimization

        public String getOptimization()
        Returns the optimization level of IBM i system Java programs that will be created if no Java program is associated with the Java class. *INTERPRET means the resulting Java program interprets the class byte codes when invoked. For other optimization levels, the Java program contains machine instruction sequences that are run when the Java program is invoked. *INTERPRET Java programs are smaller but run slower than Java programs created with higher optimization levels. As you increase the optimization level beyond 10, the Java program performance generally improves, but the time required to create the Java program increases, and debugging is more difficult.

        Possible values are:

        • 10 The Java program contains a compiled version of the class file byte codes and has only minimal additional compiler optimization. Variables can be displayed and modified while debugging.
        • *INTERPRET The Java program created does not contain machine specific instructions. It will be interpreted when the program is started. Variables can be displayed and modified while debugging. If the INTERPRET property has a value of *OPTIMIZE, all of the classes that run will be run interpreted even if there is an optimized Java program associated with the class.
        • 20 The Java program contains a compiled version of the class file byte codes and has some additional compiler optimization. Variables can be displayed but not modified while debugging.
        • 30 The Java program contains a compiled version of the class file byte codes and has more compiler optimization than optimization level 20. During a debug session, user variables cannot be changed, but can be displayed. The presented values may not be the current values of the variables.
        • 40 The Java program contains a compiled version of the class file byte codes and has more compiler optimization than optimization level 30. All call and instruction tracing is disabled.
        Returns:
        The optimization level of the IBM i system Java application.
      • getOptions

        public String[] getOptions()
        Returns a list of special options used when running the Java class.

        The possible values are:

        • *NONE No special options are used when running the Java class.
        • *VERBOSE A message is displayed each time a class file is loaded.
        • *DEBUG Allows the system debugger to be used for this Java program.
        • *VERBOSEGC A message is displayed for each garbage collection sweep.
        • *NOCLASSGC Unused classes are not reclaimed when garbage collection is run.
        Returns:
        The options used when running the Java class.
      • getParameters

        public String[] getParameters()
        Returns parameter values that are passed to the Java application. A maximum of 200 parameter values can be passed.
        Returns:
        The parameters when running the Java application.
      • getProperties

        public Properties getProperties()
        Returns the properties set on the IBM i system's JVM before running the Java program.
        Returns:
        The properties.
      • getSecurityCheckLevel

        public String getSecurityCheckLevel()
        Returns the level of warnings given for directories in the CLASSPATH that have public write authority. A directory in the CLASSPATH that has public write authority is a security exposure because it may contain a class file with the same name as the one you want to run. Whichever class file is found first is run.

        The possible values are:

        • *WARN Warning message is sent for each directory in the CLASSPATH that has public write authority.
        • *SECURE A warning message is sent for each directory in the CLASSPATH that has public write authority. If one or more warning messages are sent, an escape message is sent and the Java program is not run.
        • *IGNORE Ignore the fact that directories in the CLASSPATH may have public write authority. No warnings messages are sent.
        Returns:
        The level of warnings given for directories in the CLASSPATH that have public write authority.
      • getStandardErrorString

        public String getStandardErrorString()
        Returns the next string written to stderr by the program running on the system.
        Returns:
        the next stderr string from the system.
      • getStandardOutString

        public String getStandardOutString()
        Returns the next string written to stdout by the application.
        Returns:
        the string written to stdout.
      • getSystem

        public AS400 getSystem()
        Returns the system which contains the Java program.
        Returns:
        The system.
      • isFindPort

        public boolean isFindPort()
        Indicates if this class should search for a free port.
        Returns:
        true if this class will search for a free port; false otherwise. The default value is true.
      • sendStandardInString

        public void sendStandardInString(String data)
        Sends the stdin to the application running on the system.
        Parameters:
        data - The stdin to the system.
      • setClassPath

        public void setClassPath(String classPath)
                          throws PropertyVetoException
        Sets the value of the CLASSPATH environment variable when running the Java program. Use the forward slash to separate path elements and a colon to separate the elements of CLASSPATH. For example, /dir1:/dir1/dir2/myClasses.jar.

        Valid values are:

        • *ENVVAR No setting is sent from the client to the IBM i system so the IBM i system's default value of CLASSPATH is used.
        • string The value that is set before the program is run.
        Parameters:
        classPath - The value of the classpath.
        Throws:
        PropertyVetoException - If the change is vetoed.
      • setDefaultPort

        public void setDefaultPort(int port)
                            throws PropertyVetoException
        Sets the default port. This is the port for stdin. stdout is (port + 1) and stderr is (port + 2). setFindPort() can be used to tell this class to search for a free port if these ports are in use.
        Parameters:
        port - The default port.
        Throws:
        PropertyVetoException - If the change is vetoed.
      • setFindPort

        public void setFindPort(boolean search)
                         throws PropertyVetoException
        Sets searching for a free port.
        Parameters:
        search - true to search for a port that is not in use; false to not search. The default value is true.
        Throws:
        PropertyVetoException - If the change is vetoed.
      • setGarbageCollectionFrequency

        public void setGarbageCollectionFrequency(int frequency)
                                           throws PropertyVetoException
        Sets the relative frequency that garbage collection runs. This parameter is valid only for OS/400 V4R2 and V4R3 versions. It is ignored for V4R4 and later versions.
        Parameters:
        frequency - The relative frequency that garbage collection runs.
        Throws:
        PropertyVetoException - If the change is vetoed.
      • setGarbageCollectionInitialSize

        public void setGarbageCollectionInitialSize(int size)
                                             throws PropertyVetoException
        Sets the initial size, in kilobytes, of the garbage collection heap. This is used to prevent garbage collection from starting on small programs.

        The possible values are:

        • 2048 The default initial size is 2048 kilobytes.
        • heap-initial-size The initial value of the garbage collection heap, in kilobytes. We recommend that the initial heap size be set to 2048 kilobytes (the default) or larger.
        Parameters:
        size - The initial size of the garbage collection heap.
        Throws:
        PropertyVetoException - If the change is vetoed.
      • setGarbageCollectionMaximumSize

        public void setGarbageCollectionMaximumSize(String size)
                                             throws PropertyVetoException
        Sets the maximum size, in kilobytes, that the garbage collection heap can grow to. This is used to prevent runaway programs that consume all of the available storage. Normally, garbage collection runs as an asynchronous thread in parallel with other threads. If the maximum size is reached, all other threads are stopped while garbage collection takes place. This may adversely affect performance.

        The possible values are:

        • *NOMAX The default maximum size is not specified by the user. The maximum is determined by the system. The heap will grow until all system resources are depleted. Then a synchronous garbage collection is started to reclaim resources no longer in use.
        • heap-maximum-size The value in kilobytes that the garbage collection heap can grow to.
        Parameters:
        size - The maximum size that the garbage collection heap can grow to.
        Throws:
        PropertyVetoException - If the change is vetoed.
      • setGarbageCollectionPriority

        public void setGarbageCollectionPriority(int priority)
                                          throws PropertyVetoException
        Sets the priority of the tasks running garbage collection. This parameter is valid only for OS/400 V4R3 and V4R2 versions. It is ignored for V4R4 and later versions.
        Parameters:
        priority - The priority of the tasks running garbage collection.
        Throws:
        PropertyVetoException - If the change is vetoed.
      • setInterpret

        public void setInterpret(String interpret)
                          throws PropertyVetoException
        Sets whether all Java class files should be run interpretively.

        The possible values are:

        • *OPTIMIZE Whether all Java classes are run interpretively depends on the value specified for the OPTIMIZE property. If INTERPRET, all Java classes will be run interpretively. If any other value was specified for the OPTIMIZE property, only Java classes with Java programs created using CRTJVAPGM command and specifying OPTIMIZE(*INTERPRET) will be run interpretively.
        • *NO Only Java classes with Java programs created using CRTJVAPGM command and specifying OPTIMIZE(*INTERPRET) will be run interpretively. Java classes that need a Java program created will be created with the optimization level specified in the OPTIMIZE parameter.
        • *YES All Java classes will be run interpretively regardless of the OPTIMIZE value associated Java program. Java classes that need a Java program created will use the optimization level specified in the OPTIMIZE parameter.
        • *JIT All Java class files will be run using the just in time compiler (JIT) regardless of the OPTIMIZE value used when the associated Java program was created.
        Parameters:
        interpret - How all Java class files should be run interpretively.
        Throws:
        PropertyVetoException - If the change is vetoed.
      • setJavaApplication

        public void setJavaApplication(String application)
                                throws PropertyVetoException
        Sets the Java application to be run.
        Parameters:
        application - The Java application to be run.
        Throws:
        PropertyVetoException - If the change is vetoed.
      • setJobName

        public void setJobName(String jobname)
        Sets the name that this job will run under. The maximum length allowed is 10 characters.

        The possible values are:

        • QJVACMDSRV - The default job name.
        • *GEN - The job name will be generated from the class name.
        • string - Any generic string value.
        Parameters:
        jobname - The value of the job name.
        Since:
        i5/OS V5R3M0
      • setOptimization

        public void setOptimization(String opt)
                             throws PropertyVetoException
        Sets the optimization level of the IBM i system Java program that will be created if no Java program is associated with the Java class. For Java classes that are in a class file, the created Java program remains associated with the class file after the Java program is run. If the class is a part of a JAR or ZIP file, a temporary Java program is created to run from and then discarded. This can result in slow performance. For best performance, explicitly create a Java program for JAR and ZIP files with the Create Java Program (CRTJVAPGM) command. For *INTERPRET, the resulting Java program interprets the class byte codes when invoked. For other optimization levels, the Java program contains machine instruction sequences that are run when the Java program is invoked. INTERPRET Java programs are smaller but run slower than Java programs created with higher optimization levels. As you increase the optimization level beyond 10, the Java program performance generally improves, but the time required to create the Java program increases and debugging is more difficult.

        The possible values are:

        • 10 The Java program contains a compiled version of the class file byte codes and has only minimal additional compiler optimization. Variables can be displayed and modified while debugging.
        • *INTERPRET The Java program created does not contain machine specific instructions. It will be interpreted when the program is started. Variables can be displayed and modified while debugging. If the INTERPRET keyword has a value of *OPTIMIZE, all of the classes that run will be run interpreted even if there is an optimized Java program associated with the class.
        • *JIT No Java program containing machine instruction sequences is created. The class is run using the just in time compiler (JIT).
        • 20 The Java program contains a compiled version of the class file byte codes and has some additional compiler optimization. Variables can be displayed but not modified while debugging.
        • 30 The Java program contains a compiled version of the class file byte codes and has more compiler optimization than optimization level 20. During a debug session, user variables cannot be changed, but can be displayed. The presented values may not be the current values of the variables.
        • 40 The Java program contains a compiled version of the class file byte codes and has more compiler optimization than optimization level 30. All call and instruction tracing is disabled.
        Parameters:
        opt - The optimization level of the IBM i system Java program that will be created if no Java program is associated with the Java class.
        Throws:
        PropertyVetoException - If the change is vetoed.
      • setOptions

        public void setOptions(String[] option)
                        throws PropertyVetoException
        Sets special options used when running the Java class. This method is not additive. The list of values is replaced every time this method is called.

        The possible values are:

        • *NONE No special options are used when running the Java class.
        • *VERBOSE A message is displayed each time a class file is loaded.
        • *DEBUG Allows the system debugger to be used for this Java program.
        • *VERBOSEGC A message is displayed for each garbage collection sweep.
        • *NOCLASSGC Unused classes are not reclaimed when garbage collection is run.
        Parameters:
        option - The special options used when running the Java class.
        Throws:
        PropertyVetoException - If the change is vetoed.
      • setParameters

        public void setParameters(String[] parameters)
                           throws PropertyVetoException
        Sets one or more parameter values that are passed to the Java application. A maximum of 200 parameter values can be passed.
        Parameters:
        parameters - The parameters for the Java application.
        Throws:
        PropertyVetoException - If the change is vetoed.
      • setProperties

        public void setProperties(Properties property)
                           throws PropertyVetoException
        Sets the Java Virtual Machine properties when running the Java Application.
        Parameters:
        property - The JVM properties.
        Throws:
        PropertyVetoException - If the change is vetoed.
      • setSecurityCheckLevel

        public void setSecurityCheckLevel(String chklvl)
                                   throws PropertyVetoException
        Sets the level of warnings given for directories in CLASSPATH that have public write authority. A directory in CLASSPATH that has public write authority is a security exposure because it may contain a class file with the same name as the one you want to run. Whichever class file is found first is run.

        The possible values are:

        • *WARN Warning message is sent for each directory in the CLASSPATH that has public write authority.
        • *SECURE A warning message is sent for each directory in the CLASSPATH that has public write authority. If one or more warning messages are sent, an escape message is sent and the Java program is not run.
        • *IGNORE Ignore the fact that directories in the CLASSPATH may have public write authority. No warnings messages are sent.
        Parameters:
        chklvl - The level of warnings given for directories in the CLASSPATH that have public write authority.
        Throws:
        PropertyVetoException - If the change is vetoed.