JbyJ

dv6.0E

Introduction

JbyJ is a 4D plug-in to build a distributed system or Peer-to-Peer system using Java RMI. JbyJ provides plug-in methods to call project methods mutually between 4Ds in a network. If you use our Java class library, it enables your Java programs to call project methods of 4D in a network.

Java RMI: http://java.sun.com/javase/technologies/core/basic/rmi/index.jsp

JbyJ requires JWorld which is another plug-in to launch a Java virtual machine for JbyJ. RMI is used as a communication protocol in JbyJ. Because some firewalls block this protocol, JbyJ also supports HTTP to pass the firewalls.

System Requirements

JbyJ works with 4th Dimension / 4D Server v 6.0 or later in Mac OS and Windows. On Intel-based Macs, you need to use JbyJ with 4D v11 or later, because JbyJ cannot work in Rosetta.

The current version (JbyJ 6.0.0) requires 4D v11 or later, and Java 5 (JRE/JDK 1.5) or later on both platforms.

License Types

JbyJ has two license types JbyJ STD and JbyJ PRO:

JbyJ STD
This license type accepts connections from 4Ds. But it doesn't accept connections from any Java programs.
JbyJ PRO
This license type accepts connections from 4Ds like JbyJ STD. In addition, it accepts connections from Java programs in which our class library is used.

JbyJ Terms

In this manual we use new terms JbyJ Server, JbyJ Client and Remote Method:

JbyJ Server
A JbyJ Server is a 4D using JbyJ, which accepts connections from other 4Ds or Java programs in a network. A JbyJ Server has the processes in which project methods requested by other 4Ds or Java programs are executed.
JbyJ Client
A JbyJ Client is a 4D using JbyJ or Java program using our class library, which connects to a JbyJ Server in a network and calls its project methods.
Remote Method
A remote method is a 4D project method in a JbyJ Server. It is called from JbyJ Clients.

A 4D using JbyJ can be a JbyJ Server and a JbyJ Client simultaneously.

Method Group

The plug-in methods in JbyJ are classified into three groups as follows:

JbyJ Server Methods
These methods are used by a JbyJ Server.
JbyJ Client Methods
These methods are used by a JbyJ Client.
Utilities
These methods are used by both a JbyJ Server and Client.

JbJ Start server ( ClientProcesses; OnConnected; OnDisconnected ) --> Status [ C_LONGINT ]

Parameter

Type

Description

ClientProcesses

ARRAY LONGINT

Array whose elements are process numbers, in which methods requested by JbyJ Clients will be executed.

OnConnected

C_TEXT

Name of a method which is automatically called when a JbyJ Client opens a connection.

OnDisconnected

C_TEXT

Name of a method which is automatically called when a JbyJ Client closes the connection.

Call JbJ Start server to start accepting connections from JbyJ Clients.

In ClientProcesses, specify a long integer array or an integer array whose elements are process numbers, in which JbJ HANDLE CLIENT REQUESTS is called to execute methods requested by JbyJ Clients.

In OnConnected, specify the name of a method which will be automatically called in a JbyJ Server when JbJ Connect server or JbJ Connect server by servlet is called in a JbyJ Client. A client ID is passed to that method as a prameter by which the JbyJ Client can be identified. If you accept the connection from the JbyJ Client, return "True". If you refuse the connection, return "False".

In OnDisconnected, specify the name of a method which will be automatically called in a JbyJ Server when JbJ Disconnect server is called in a JbyJ Client. A client ID is passed to that method as a prameter by which the JbyJ Client can be identified. You need to return nothing in that method.

This method returns 0, if there is no error. If any error occurred, it returns a negative number. Refer to Error Number.

Example Code

`Start as a JbyJ Server
`
C_LONGINT($x;$Err)
ARRAY LONGINT(aClientProcess;10)  `10 Clients
For($x;1;Size of array(aClientProcess))
  aClientProcess{$x}:=New process("ClientRequestHandler";64000;"ClientRequestHandler"+String($x))
End for
$Err:=JbJ Start server(aClientProcess;"OnClientConnected";"OnClientDisconnected")
If($Err # 0)
  ALERT("Error:JbJ Start server")
End if 
`"ClientRequestHandler" method
`
Repeat
  PAUSE PROCESS(Current process)
  JbJ HANDLE CLIENT REQUESTS
Until(False)
 
`"OnClientConnected" method
`
C_LONGINT($1)  `ClientID
`
C_LONGINT($PortNo)
C_TEXT($UserName;$Password;$StructureName;$DataName)
C_TEXT($IPAddress)
`
$UserName:=JbJ Get client name($1)
$Password:=JbJ Get client password($1)
$StructureName:=JbJ Get client structure name($1)
$DataName:=JbJ Get client data name($1)
$IPAddress:=JbJ Get client address($1)
$PortNo:=JbJ Get client port ($1)
..........
..........

C_BOOLEAN($0)
$0:=True  `True--Accept the connection  False--Refuse the connection
 
`"OnClientDisconnected" method
`
C_LONGINT($1)  `ClientID
C_LONGINT($PortNo)
C_TEXT($UserName;$Password;$StructureName;$DataName)
C_TEXT($IPAddress)
`
$UserName:=JbJ Get client name($1)
$Password:=JbJ Get client password($1)
$StructureName:=JbJ Get client structure name($1)
$DataName:=JbJ Get client data name($1)
$IPAddress:=JbJ Get client address($1)
$PortNo:=JbJ Get client port($1)
..........
..........

JbJ HANDLE CLIENT REQUESTS

Parameter

Type

Description

(No patameter)

JbJ HANDLE CLIENT REQUESTS handles requests of a JbyJ Client. Methods requested by the JbyJ Client are executed in this method.

Refer to Example Code for JbJ Start server.
JbJ Get client name ( ClientID ) --> UserName [ C_TEXT ]

Parameter

Type

Description

ClientID

C_LONGINT

Client ID

JbJ Get client name returns the user name of the JbyJ Client identified by ClientID.

If any error occurred, this method returns "".

JbJ Get client password ( ClientID ) --> Password [ C_TEXT ]

Parameter

Type

Description

ClientID

C_LONGINT

Client ID

JbJ Get client password returns the password of the JbyJ Client identified by ClientID.

If any error occurred, this method returns "".

JbJ Get client structure name ( ClientID ) --> StructureFileName [ C_TEXT ]

Parameter

Type

Description

ClientID

C_LONGINT

Client ID

JbJ Get client structure name returns the structure file name of the JbyJ Client identified by ClientID. If the JbyJ client is a Java client, this method will return "Java".

If any error occurred, this method returns "".
JbJ Get client data name ( ClientID ) --> DataFileName [ C_TEXT ]

Parameter

Type

Description

ClientID

C_LONGINT

Client ID

JbJ Get client data name returns the data file name of the JbyJ Client identified by ClientID. If the JbyJ client is a Java client, this method will return "Java".

If any error occurred, this method returns "".
JbJ Get client address ( ClientID ) --> IPAddress [ C_TEXT ]

Parameter

Type

Description

ClientID

C_LONGINT

Client ID

JbJ Get client address returns the IP address or host name of the computer in which the JbyJ Client identified by ClientID is running.

If any error occurred, this method returns "".
JbJ Get client port ( ClientID ) --> PortNumber [ C_LONGINT ]

Parameter

Type

Description

ClientID

C_LONGINT

Client ID

JbJ Get client port returns the port number of the JbyJ Client identified by ClientID.

If any error occurred, this method returns a negative number. Refer to Error Number.
JbJ Get client process ( ClientID ) --> ProcessNumber [ C_LONGINT ]

Parameter

Type

Description

ClientID

C_LONGINT

Client ID

JbJ Get client process returns the process number in which methods requested by the JbyJ Client identified by ClientID will be executed.

If any error occurred, this method returns a negative number. Refer to Error Number.

Refer to JbJ Get client id.
JbJ Get client id ( ProcessNo ) --> ClientID [ C_LONGINT ]

Parameter

Type

Description

ProcessNo

C_LONGINT

Process number

JbJ Get client id returns the client ID of the JbyJ Client whose requested methods will be executed in the process identified by ProcessNo .

If any error occurred, this method returns a negative number. Refer to Error Number.

Refer to JbJ Get client process.
JbJ Disconnect client ( ClientID ) --> Status [ C_LONGINT ]

Parameter

Type

Description

ClientID

C_LONGINT

Client ID

JbJ Disconnect client closes the connection with the JbyJ Client identified by ClientID. In this case the connection is closed by a JbyJ Server. The JbyJ Client doesn't know that the connection is closed.

This method returns 0, if there is no error. If any error occurred, it returns a negative number. Refer to Error Number.
JbJ Connect server ( IPAddress; PortNo; UserName; Password ) --> ServerID [ C_LONGINT ]

Parameter

Type

Description

IPAddress

C_TEXT

IP address or host name

PortNo

C_LONGINT

Port number

UserName

C_TEXT

User name

Password

C_TEXT

Password

JbJ Connect server establishes a connection with a JbyJ Server and returns a server ID by which the JbyJ Server is identified. The RMI protocal is used for this connection.

In IPAddress, specify an IP address or host name of the computer in which a JbyJ Server is runing.

In PortNo, specify a port number of the JbyJ Server.

In UserName, specify your user name.

In Password, specify your password.

If any error occurred, it returns a negative number. Refer to Error Number.

Refer to JbJ Connect server by servlet.

Refer to Example Code for JbJ Call remote method.
JbJ Connect server by servlet ( ServletURL; IPAddress; PortNo; UserName; Password ) --> ServerID [ C_LONGINT ]

Parameter

Type

Description

SevletURL

C_TEXT

URL of the JbyJAdaptor servlet

IPAddress

C_LONGINT

IP address or host name

PortNo

C_TEXT

Port number

UserName

C_TEXT

User name

Password

C_TEXT

Password

JbJ Connect server by servlet establishes a connection with a JbyJ Server via the JbyJAdaptor servlet and returns a server ID by which the JbyJ Server is identified.

This method uses two protocols HTTP and RMI for the connection because some firewalls block the RMI protocol. For this connection a HTTP server and the JbyJAdaptor servlet we provide are required. The JbyJAdaptor servlet in a HTTP server works as a mediator between HTTP and RMI.

In ServletURL, specify the URL of the JbyJAdaptor. The URL will be “http://xxx.xxx.xxx/JbyJAdaptor“ or “http://xxx.xxx.xxx:xxxx/JbyJAdaptor“ for example.

In IPAddress, specify an IP address or host name of the computer in which a JbyJ Server is running.

In PortNo, specify a port number of the JbyJ Server.

In UserName, specify your user name.

In Password, specify your password.

If any error occurred, it returns a negative number. Refer to Error Number.

Refer to JbJ Connect server.

Refer to Example Code for JbJ Call remote method.
JbJ Call remote method ( ServerID; MethodName; Parameters; Async ) --> Status [ C_LONGINT ]

Parameter

Type

Description

ServerID

C_LONGINT

Server ID

MethodName

C_TEXT

Name of a remote method

Parameters

ARRAY POINTER

Pointer array whose elements point to parameters to be passed to a remote method

Async

C_LONGINT

0 or 1

JbJ Call remote method calls a remote method. Until the connection is closed, remote methods called by this method are executed in an exclusive process in the JbyJ Server. Therefore the process variables, the current record and the current selection are not changed between calls.

In ServerID, specify a ID number JbJ Connect server or JbJ Connect server by servlet returned.

In MethodName, specify a remote method name.

In Params, specify a pointer array whose elements point to parameters to be passed to the remote method. The results of the remote method are returned through Params. After the remote method is executed, the size of Params may be changed and its elements will point to the results returned by the remote method.

If 0 is specified in Async, the remote method is executed synchronously. If 1 is specified in Async, the remote method is executed asynchronously. If the remote method returns nothing, it can be executed asynchronously.

This method returns 0, if there is no error. If any error occurred, it returns a negative number. Refer to Error Number.

Example Code

`Call remote methods
`
C_LONGINT($ServerID)
` $ServerID:=JbJ Connect server ("www.xxx.com";9999;"Monica";"WhiteHouse")
` or
$ServerID:=JbJ Connect server by servlet (
                              "http://www.xxx.com:8080/JbyJAdaptor";
                              "www.xxx.com";
                              9999;
                              "Monica";
                              "WhiteHouse")
If($ServerID>0)
  C_TEXT($StructureName;$DataName)
`
  $StructureName:=JbJ Get server structure name($ServerID)
  $DataName:=JbJ Get server data name($ServerID)
`
  C_BOOLEAN(vSex)
  C_TEXT(vName)
  C_LONGINT(vHisAge)
  C_LONGINT($Err)
`
  vSex:=True  `Male
  vName:="Bill Clinton"
  ARRAY TEXT(aHisChildren;3)
  aHisChildren{1}:="John"
  aHisChildren{2}:="Mary"
  aHisChildren{3}:="Mike"
`
  ARRAY POINTER($Parameter;2)
  $Parameter{1}:=->vSex           `1st parameter
  $Parameter{2}:=->vName          `2nd parameter
  $Err:=JbJ Call remote method($ServerID;"TestMethod1";$Parameter;0)
  If($Err=0)
    If(Size of array($Parameter)=1)
      If(Type($Parameter{1}->)=Is LongInt)
        vHisAge:=$Parameter{1}->                  `receive a result
      Else
        ALERT("Error:JbJ Call remote method")
      End if
    Else
      ALERT("Error:JbJ Call remote method")
    End if
  Else
    ALERT("Error:JbJ Call remote method")
  End if
`
  ARRAY POINTER($Parameter;3)
  $Parameter{1}:=->vSex           `1st parameter
  $Parameter{2}:=->vName          `2nd parameter
  $Parameter{3}:=->aHisChildren   `3rd parameter
  $Err:=JbJ Call remote method($ServerID;"TestMethod2";$Parameter;0)
  If($Err=0)
    If(Size of array($Parameter)=1)
      If(Type($Parameter{1}->)=LongInt array)
        ARRAY LONGINT(aSalary;0)
        COPY ARRAY($Parameter{1}->;aSalary)      `receive a result (array)
      Else
        ALERT("Error:JbJ Call remote method")
      End if
    Else
      ALERT("Error:JbJ Call remote method")
    End if
  Else
    ALERT("Error:JbJ Call remote method")
  End if
`
  ARRAY POINTER($Parameter;3)
  $Parameter{1}:=->vSex           `1st parameter
  $Parameter{2}:=->vName          `2nd parameter
  $Parameter{3}:=->aHisChildren   `3rd parameter
  $Err:=JbJ Call remote method($ServerID;"TestMethod3";$Parameter;0)
  If($Err=0)
    If(Size of array($Parameter)=2)
      If(Type($Parameter{1}->)=Is LongInt) & (Type($Parameter{2}->)=LongInt array)
        vHisAge:=$Parameter{1}->                 `receive the 1st result
        ARRAY LONGINT(aSalary;0)
        COPY ARRAY($Parameter{2}->;aSalary)     `receive the 2nd result (array)
      Else
        ALERT("Error:JbJ Call remote method")
      End if
    Else
      ALERT("Error:JbJ Call remote method")
    End if
  Else
    ALERT("Error:JbJ Call remote method")
  End if
`
  $Err:=JbJ Disconnect server($ServerID)
  If($Err # 0)
    ALERT("Error:JbJ Disconnect server")
  End if
`
Else
  ALERT("Error:JbJ Connect server")
End if 
`"TestMethod1" in a JbyJ Server
`
C_BOOLEAN($1)    `Sex
C_TEXT($2)  `Name
..........
..........

C_LONGINT($0)
QUERY([Personnel];[Personnel]Sex=$1;*)
QUERY([Personnel]; & ;[Personnel]Name=$2)
$0:=[Personnel]Age
 
`"TestMethod2" in a JbyJ Server
`
C_BOOLEAN($1)    `Sex
C_TEXT($2)  `Name
C_POINTER($3)    `His children
`
C_LONGINT($Size;$x)
$Size:=Size of array($3->)
ARRAY TEXT(aHisChildren;$Size)
For($x;1;$Size)
  aHisChildren{$x}:=$3->{$x}
End for
..........
..........

QUERY([Personnel];[Personnel]Sex=$1;*)
QUERY([Personnel]; & ;[Personnel]Name=$2)
RELATE MANY([Personnel]ID)
ARRAY LONGINT(aSalary;0)
SELECTION TO ARRAY([Salary]Paid;aSalary)
`
C_POINTER($0)
$0:=->aSalary
 
`"TestMethod3" in a JbyJ Server
`
C_BOOLEAN($1)    `Sex
C_TEXT($2)  `Name
C_POINTER($3)    `His children
`
C_LONGINT($Size;$x)
$Size:=Size of array($3->)
ARRAY TEXT(aHisChildren;$Size)
For($x;1;$Size)
  aHisChildren{$x}:=$3->{$x}
End for
..........
..........

QUERY([Personnel];[Personnel]Sex=$1;*)
QUERY([Personnel]; & ;[Personnel]Name=$2)
RELATE MANY([Personnel]ID)
ARRAY LONGINT(aSalary;0)
SELECTION TO ARRAY([Salary]Paid;aSalary)
`
ARRAY POINTER(aReturn;2)
aReturn{1}:=->[Personnel]Age
aReturn{2}:=->aSalary
`
C_POINTER($0)
$0:=->aReturn

JbJ Disconnect server ( ServerID ) --> Status [ C_LONGINT ]

Parameter

Type

Description

ServerID

C_LONGINT

Server ID

JbJ Disconnect server terminates the connection with the JbyJ Server identified by ServerID.

This method returns 0, if there is no error. If any error occurred, it returns a negative number. Refer to Error Number.

Refer to Example Code for JbJ Call remote method.
JbJ Get server structure name ( ServerID ) --> StructureFileName [C_TEXT]

Parameter

Type

Description

ServerID

C_LONGINT

Server ID

JbJ Get server structure name returns the structure file name of the JbyJ Server identified by ServerID.

If any error occurred, this method returns "".
JbJ Get server data name ( ServerID ) --> DataFileName [C_TEXT]

Parameter

Type

Description

ServerID

C_LONGINT

Server ID

JbJ Get server data name returns the data file name of the JbyJ Server identified by ServerID.

If any error occurred, this method returns "".
JbJ Get servlet url ( ServerID ) --> ServletURL [C_TEXT]

Parameter

Type

Description

ServerID

C_LONGINT

Server ID

JbJ Get servlet url returns the servlet URL, if the connection is established by JbJ Connect server by servlet. This method returns "", if the connection is established by JbJ Connect server.

If any error occurred, this method also returns "".
JbJ Get server address ( ServerID ) --> IPAddress [C_TEXT]

Parameter

Type

Description

ServerID

C_LONGINT

Server ID

JbJ Get server address returns the IP address or host name of the computer in which the JbyJ Server identified by ServerID is running.

If any error occurred, this method returns "".
JbJ Get server port ( ServerID ) --> PortNumber [ C_LONGINT ]

Parameter

Type

Description

ServerID

C_LONGINT

Server ID

JbJ Get server port returns the port number of the JbyJ Server identified by ServerID.

If any error occurred, this method returns a negative number. Refer to Error Number.
JbJ Get my client id ( ServerID ) --> ClientID [ C_LONGINT ]

Parameter

Type

Description

ServerID

C_LONGINT

Server ID

JbJ Get my client id returns the client ID by which this client is identified on the JbyJ Server identified by ServerID.

If any error occurred, this method returns a negative number. Refer to Error Number.
JbJ Get my address --> IPAddress [C_TEXT]

Parameter

Type

Description

(No patameter)

JbJ Get my address returns the IP address of your computer.

If any error occurred, this method returns "".
JbJ Get my host name --> HostName [C_TEXT]

Parameter

Type

Description

(No patameter)

JbJ Get my host name returns the host name of your computer. If your computer has not a host name, this method returns the IP address.

If any error occurred, this method returns "".
JbJ Copy record to BLOB ( TableNo; BLOB ) --> Status [ C_LONGINT ]

Parameter

Type

Description

TableNo

C_LONGINT

Table number

BLOB

C_BLOB

BLOB in which the current record will be copied.

JbJ Copy record to BLOB copies the current record of a table whose number is passed in TableNo into BLOB.

If any error occurred, this method returns a negative number. Refer to Error Number.
JbJ Copy BLOB to record ( BLOB; TableNo ) --> Status [ C_LONGINT ]

Parameter

Type

Description

BLOB

C_BLOB

BLOB in which a record has been copied.

TableNo

C_LONGINT

Table number

JbJ Copy BLOB to record replaces the current record of a table whose number is passed in TableNo with BLOB, in which a record has been copied by using JbJ Copy record to BLOB.

If any error occurred, this method returns a negative number. Refer to Error Number.
JbJ Set environment ( JVM_ID; ProductType; PortNo ) --> Status [ C_LONGINT ]

Parameter

Type

Description

JVM_ID

C_LONGINT

ID for a Java virtual machine JWD create java world returns

ProductType

C_TEXT

"PRODUCT" or "TRIAL"

PortNo

C_LONGINT

Port number

JbJ Set environment setups the environment for JbyJ. This method has to be executed before executing any other JbyJ plug-in methods. This method is usually called at "On Startup".

In JVM_ID, specify an ID number for a Java virtual machine which JWD create java world returns.

In ProductType, Specify "PRODUCT" normally. If you want to use your application with JbyJ in trial mode, specify "TRIAL".

In PortNo, specify a port number your JbyJ Server will use. We recommend to use 9000's for a JbyJ Server to avoid conflicting with other applications.

This method returns 0, if there is no error. If any error occurred, it returns a negative number. Refer to Error Number.

Example Code

`Setup the environment for JbyJ in "On Startup" method
`
C_LONGINT($JVM_ID)
C_LONGINT($Err)
`
$JVM_ID:=JWD Create java world("BUIT-IN")
If($JVM_ID>0)
  $Err:=JbJ Set environment($JVM_ID;"PRODUCT";9999)
  If($Err # 0)
    ALERT("Error:JbJ Set environment")
  End if
Else
  ALERT("Error:JWD Create java world")
End if

JWorld

JWorld is a plug-in for 4D to launch a Java virtual machine (JVM). JbyJ itself doesn't launch it. JWorld has following plug-in methods:

JWD Create java world
JWD Close java world
JWD Convert line separator
JWD Set JVM options

In Mac OS, Apple's built-in JVM is launched by JWorld. In Windows, if JWorld 6.0.0 or later is used, JWorld's built-in JVM is launched. If JWorld 5.x.x or earlier version is used in Windows, you have to install a JVM which is downloadable at the following URL:

http://java.sun.com/javase/downloads/

JWD Create java world ( JVM_Path )--> JVM_ID [ C_LONGINT ]

Parameter

Type

Description

JVM_Path

C_TEXT

"BUILT-IN", "" (blank) or a path to jvm.dll (wondows)

JWD Create java world launches a Java virtual machine (JVM) and returns its ID number.

In Mac OS, JVM_Path is always ignored and Apple's built-in JVM is launched. In Windows, specify "BUILT-IN", "" (blank) or a path to jvm.dll in JVM_Path.

If "BUILT-IN" is specified in JVM_Path using JWorld 6.0.0 or later in Windows, JWorld's built-in JVM is launched. This built-in JVM is "JRE version 6 Update 18" , which is located "Plugins/JWorld_xxx.bundle/Contents/Windows/JRE". If the built-in JVM is not found in the directory, it is considered that "" (blank) is specified in JVM_Path. If JWorld 5.x.x or earlier is used, it is also considered that "" (blank) is specified.

If "" (blank) is specified in JVM_Path in Windows, your installed JVM is launched referring to the Registry.

If a path to jvm.dll is specified in JVM_Path in Windows, the JVM identified by the path is launched.

Example of the path to jvm.dll in Windows
JRE 1.6.0_02 "C:\Program Files\Java\jre1.6.0_02\bin\client\jvm.dll"
JDK 1.6.0_02 "C:\Program Files\Java\jdk1.6.0_02\jre\bin\client\jvm.dll"

This plug-in method should be called in "On Startup" or in a process started in "On Server Startup".

This method returns a positive number (JVM_ID), if there is no error. If any error occurred, it returns a negative number. Refer to Error Number.

Example Code

C_LONGINT($JVM_ID)
C_LONGINT($Err)
`
ARRAY TEXT($Options;2)
$Options{1}:="-Xms128M"
$Options{2}:="-Xmx128M"
$Err:=JWD Set JVM options( $Options )
If($Err=0)
  $JVM_ID:=JWD Create java world("BUILT-IN")
  If($JVM_ID>0)
    $Err:=JbJ Set environment($JVM_ID;"PRODUCT";9999)
    If($Err # 0)
      ALERT("Error:JbJ Set environment")
    End if
  Else
    ALERT("Error:JWD Create java world")
  End if 
Else
  ALERT("Error:JWD Set JVM options")
End if

JWD Close java world --> Status [ C_LONGINT ]

Parameter

Type

Description

(None)

JWD Close java world terminates JWorld. Call this method in "On Exit" or "On Server Shutdown".

This method returns 0, if there is no error. If any error occurred, it returns a negative number. Refer to Error Number.

Example Code

C_LONGINT($Err)
$Err:=JWD Close java world

JWD Convert line separator ( Switch ) --> Status [ C_LONGINT ]

Parameter

Type

Description

Switch

C_BOOLEAN

If Switch is True, Line separators are converted (CR <-> LF). If Switch is False, they are not converted.

If "True" is passed to JWD Convert line separator, all CRs (carriage return) are automatically converted to LFs (line feed) when 4D strings are sent to Java. And all LFs are automatically converted to CRs when Java strings are sent to 4D.

If "False" is passed to this method, any line separators are not converted.

This method returns 0, if there is no error. If any error occurred, it returns a negative number. Refer to Error Number.

Example Code

C_LONGINT($Err)
$Err:=JWD Convert line separator( True )

JWD Set JVM options ( Options ) --> Status [ C_LONGINT ]

Parameter

Type

Description

Options

ARRAY TEXT

Text array whose elements are JVM options.

JWD Set JVM options sets Java virtual machine options. Pass a text array whose elements are the options. Call this method before JWD Create java world is executed. Refer to the following web page about JVM options:

http://blogs.sun.com/watt/resource/jvm-options-list.html

If an option "-Djworld.stdout.redirect=true" is set, stdout and stderr can be redirected to a file whose name is "jworldout.txt" which is located in the same level as the structure file.

This method returns 0, if there is no error. If any error occurred, it returns a negative number. Refer to Error Number.

Example Code

C_LONGINT($Err)
C_LONGINT($JVM_ID)
`
ARRAY TEXT($Options;3)
$Options{1}:="-Xms128M"
$Options{2}:="-Xmx128M"
$Options{3}:="-Djworld.stdout.redirect=true"
`
$Err:=JWD Set JVM options( $Options )
If ($Err=0)
    $JVM_ID:=JWD Create java world( "" )
    ...
End if

Java Class Library

We provide Java developers with a class library JbyJClasses to develop JbyJ Clients written in Java. The class library has the following classes.

com.ronri_kobo.JbyJ.JbyJ4DServe

com.ronri_kobo.Time

com.ronri_kobo.Date

com.ronri_kobo.Picture

com.ronri_kobo.JbyJ.InvalidLicenseCodeException

com.ronri_kobo.JbyJ.RefuseConnectionException

com.ronri_kobo.JbyJ.FullEntryException

com.ronri_kobo.JbyJ.ShutOutException
com.ronri_kobo.JbyJ.MethodErrorException

Class com.ronri_kobo.JbyJ.JbyJ4DServer

java.lang.Object
   |
   +----com.ronri_kobo.JbyJ.JbyJ4DServer
public class JbyJ4DServer extends java.lang.Object

A instance of this class is used as a stub of a JbyJ Server. This class has 2 constructors and 8 instance methods as follows:

JbyJ4DServer

public JbyJ4DServer(java.lang.String ipaddress,
                    int portNo,
                    java.lang.String userName,
                    java.lang.String password)
                    throws com.ronri_kobo.JbyJ.InvalidLicenseCodeException,
                           com.ronri_kobo.JbyJ.RefuseConnectionException,
                           com.ronri_kobo.JbyJ.FullEntryException,
                           java.net.UnknownHostException,
                           java.rmi.RemoteException,
                           java.rmi.NotBoundException,
                           java.rmi.MalformedURLException,
                           java.io.IOException,
                           java.lang.Exception

By this constructor, a connection is established with a JbyJ Server identified by ipaddress and portNo. The RMI protocal is used for this connection.

In userName, specify your user name.

In password, specify your password.

This Java method corresponds with the plug-in method JbJ Connect server.

JbyJ4DServer

public JbyJ4DServer(java.lang.String servletURL,
                    java.lang.String ipaddress,
                    int portNo,
                    java.lang.String userName,
                    java.lang.String password)
                    throws com.ronri_kobo.JbyJ.InvalidLicenseCodeException,
                           com.ronri_kobo.JbyJ.RefuseConnectionException,
                           com.ronri_kobo.JbyJ.FullEntryException,
                           java.net.UnknownHostException,
                           java.rmi.RemoteException,
                           java.rmi.NotBoundException,
                           java.rmi.MalformedURLException,
                           java.io.IOException,
                           java.lang.Exception,
                           java.lang.ClassNotFoundException

By this constructor, a connection is established with a JbyJ Server identified by ipaddress and portNo via the servlet whose URL is specified in servletURL. HTTP and RMI are used for this connection in order to pass firewall.

In userName, specify your user name.

In password, specify your password.

This Java method corresponds with the plug-in method JbJ Connect server by servlet.

call4DMethod

public java.lang.Object call4DMethod(java.lang.String methodName,
                                     java.lang.Object[] parameter,
                                     int async)
                                     throws com.ronri_kobo.JbyJ.ShutOutException,
                                            com.ronri_kobo.JbyJ.MethodErrorException,
                                            java.net.UnknownHostException,
                                            java.rmi.RemoteException,
                                            java.rmi.NotBoundException,
                                            java.rmi.MalformedURLException,
                                            java.io.IOException,
                                            java.lang.Exception

This method calls a remote method whose name is specified in methodName. Until the connection is closed, remote methods called by this Java method are executed in an exclusive process in the JbyJ Server. Therefore the process variables, the current record and the current selection are not changed between calls.

In parameter, specify an array of the Object class whose elements are parameters to be passed to the remote method. To pass values of primitive types (int, double...), the wrapper objects must be created for them.

If 0 is specified in aync, the remote method is executed synchronously. If 1 is specified in aync, the remote method is executed asynchronously. If the remote method returns nothing, it can be executed asynchronously.

This Java method always returns an object of the Object class which corresponds with $0 in the remote method. The object will be unwrapped or cast to use in your program.

If the remote method returns a pointer to a ARRAY POINTER, this Java method returns an array of the Object class whose elements correspond with the elements of the ARRAY POINTER. The elements of the array will be unwrapped or cast to use in your program.

This Java method corresponds with the plug-in method JbJ Call remote method.

Refer to Type Conversion between 4D and Java.

disconnect

public void disconnect() throws com.ronri_kobo.JbyJ.ShutOutException,
                                java.net.UnknownHostException,
                                java.rmi.RemoteException,
                                java.rmi.NotBoundException,
                                java.rmi.MalformedURLException,
                                java.io.IOException

This method terminates the connection with the JbyJ Server.

This Java method corresponds with the plug-in method JbJ Disconnect server.

getStructureName

public java.lang.String getStructureName()

This method returns the structure file name of the JbyJ Server.

This method corresponds with JbJ Get server structure name.

getDataName

public java.lang.String getDataName()

This method returns the data file name of the JbyJ Server.

This Java method corresponds with the plug-in method JbJ Get server data name.

getServletURL

public java.lang.String getServletURL()

This method returns the URL of the servlet, if the connection is established using the servlet. This method returns "", if the connection is established not using the servlet.

This Java method corresponds with the plug-in method JbJ Get servlet url.

getAddress

public java.lang.String getAddress()

This method returns the IP address or host name of the computer in which the JbyJ Server is running.

This Java method corresponds with the plug-in method JbJ Get server address.

getPort

public int getPort()

This method returns the port number of the JbyJ Server.

This Java method corresponds with the plug-in method JbJ Get server port.

getMyClientID

public int getMyClientID()

This method returns the client ID by which this client is identified on the JbyJ Server.

This Java method corresponds with the plug-in method JbJ Get my client id.

Example Code

import java.lang.*;
import com.ronri_kobo.*;
import com.ronri_kobo.JbyJ.*;

public class TestClass
{
  ..........
  ..........

  /**************************/
  // execute4Dmethod
  /**************************/
  public void execute4Dmethod()
  {
    try{

      // JbyJ4DServer server  = new JbyJ4DServer( "www.xxx.com", 
      //                                          9999, 
      //                                          "Monica", 
      //                                          "Whitehouse" );

      JbyJ4DServer server  = new JbyJ4DServer(
                        "http://www.xxx.com:8080/JbyJAdaptor", 
                        "www.xxx.com", 
                        9999, 
                        "Monica", 
                        "Whitehouse" );

      String structureName = server.getStructureName();
      String dataName      = server.getDataName();

      Object[] params;
      Object[] results;
      Object   resultObj;
      int      hisAge;
      int[]    hisSalary;

      boolean  sex         = true; //Male
      String   name        = "Bill Clinton";
      String[] hisChildren = new String[ 3 ];
      hisChildren[ 0 ]     = "John";
      hisChildren[ 1 ]     = "Mary";
      hisChildren[ 2 ]     = "Mike";

      params      = new Object[ 2 ];
      params[ 0 ] = new Boolean( sex );   // 1st Parameter
      params[ 1 ] = name;                 // 2nd Parameter
      resultObj   = server.call4DMethod( "TestMethod1", params, 0 );
      hisAge      = ( (Integer)resultObj).intValue();

      params      = new Object[ 3 ];
      params[ 0 ] = new Boolean( sex );   // 1st Parameter
      params[ 1 ] = name;                 // 2nd Parameter
      params[ 2 ] = hisChildren;          // 3rd Parameter
      resultObj   = server.call4DMethod( "TestMethod2", params, 0 );
      hisSalary   = (int[])resultObj;

      resultObj   = server.call4DMethod("TestMethod3", params, 0 );
      resultArray = (Object[])resultObj;
      hisAge      = ( (Integer)( resultArray[ 0 ] ) ).intValue();
      hisSalary   = (int[])( resultArray[ 1 ] );

      server.disconnect();

    }catch( Exception e ) { System.err.println( "" + e ); }
  }
  ..........
  ..........
}

Class com.ronri_kobo.Time

java.lang.Object
   |
   +----com.ronri_kobo.Time
public class Time extends java.lang.Object implements java.io.Serializable

This class corresponds with C_TIME in 4D and its objects are used when you pass parameters to 4D methods or receive results from them.

Time

public Time(int hour, int min, int sec)

This method creates an object of the Time class and initializes its hour, minute and second with specified values.

getHours

public int getHours()

This method returns the hour of the Time object.

getMinutes

public int getMinutes()

This method returns the minute of the Time object.

getSeconds

public int getSeconds()

This method returns the second of the Time object.

setHours

public void setHours(int hour)

This method replaces the current hour of the Time object with a specified value.

setMinutes

public void setMinutes(int min)

This method replaces the current minute of the Time object with a specified value.

setSeconds

public void setSeconds(int sec)

This method replaces the current second of the Time object with a specified value.

Class com.ronri_kobo.Date

java.lang.Object
   |
   +----com.ronri_kobo.Date
public class Date extends java.lang.Object implements java.io.Serializable

This class corresponds with C_DATE in 4D and its objects are used when you pass parameters to 4D methods or receive results from them.

Date

public Date(int year, int month, int date)

This method creates an object of the Date class and initializes its year, month and date with specified values.

getYear

public int getYear()

This method returns the year (0-32767) of the Date object.

getMonth

public int getMonth()

This method returns the month (1-12) of the Date object.

getDate

public int getDate()

This method returns the date (1-31) of the Date object.

setYear

public void setYear(int year)

This method replaces the current year of the Date object with a specified value (0-32767).

setMonth

public void setMonth(int month)

This method replaces the current month of the Date object with a specified value (1-12).

setDate

public void setDate(int date)

This method replaces the current day of the Date object with a specified value (1-31).

Class com.ronri_kobo.Picture

java.lang.Object
   |
   +----com.ronri_kobo.Picture
public class Picture extends java.lang.Object implements java.io.Serializable

This class corresponds with C_PICTURE in 4D and its objects are used when you pass parameters to 4D methods or receive results from them.

Picture

public Picture(byte picture[])

This method creates an object of the Picture class and initializes it with the specified byte array.

getBytes

public byte[] getBytes()

This method converts the Picture object into a byte array and returns it.

setBytes

public void setBytes(byte picture[])

This method converts the specified byte array into a Picture object and replaces the current Picture object with it.

Class com.ronri_kobo.JbyJ.InvalidLicenseCodeException

java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----com.ronri_kobo.JbyJ.InvalidLicenseCodeException
public class InvalidLicenseCodeException extends java.lang.Exception

This exception occurs when you try to connect to a JbyJ Server by JbyJ4DServer and the JbyJ Server doesn't have a valid license key code to accept connections from Java programs.

InvalidLicenseCodeException

 public InvalidLicenseCodeException()

Class com.ronri_kobo.JbyJ.RefuseConnectionException

java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----com.ronri_kobo.JbyJ.RefuseConnectionException
public class RefuseConnectionException extends java.lang.Exception

This exception occurs when you try to connect to a JbyJ Server by JbyJ4DServer and the connection was refused by the JbyJ Server.

Refer to Example Code for JbJ Start server.

RefuseConnectionException

 public RefuseConnectionException()

Class com.ronri_kobo.JbyJ.FullEntryException

java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----com.ronri_kobo.JbyJ.FullEntryException
public class FullEntryException extends java.lang.Exception

This exception occurs when you try to connect to a JbyJ Server by JbyJ4DServer and the JbyJ Server does not have any vacant processe to handle client's requests.

Refer to JbJ Start server.

FullEntryException

 public FullEntryException()

Class com.ronri_kobo.JbyJ.ShutOutException

java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----com.ronri_kobo.JbyJ.ShutOutException
public class ShutOutException extends java.lang.Exception

This exception occurs when you try to execute call4DMethod or disconnect and the connection with the JbyJ Server had been already closed. A JbyJ Server can disconnect with the clients by JbJ Disconnect client.

ShutOutException

 public ShutOutException()

Class com.ronri_kobo.JbyJ.MethodErrorException

java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----com.ronri_kobo.JbyJ.MethodErrorException
public class MethodErrorException extends java.lang.Exception

This exception occurs when an invalid 4D method name is passed to call4DMethod or invalid parameters are passed to call4DMethod.

MethodErrorException

 public MethodErrorException()

Type Mapping

When passing parameters to a remote method or receiving results from a remote method in Java programs, their data types are automatically converted as follows:

4D

Java

C_BOOLEAN

<->

boolean

C_INTEGER

->

int

C_LONGINT

<->

int

C_REAL

<->

double

C_TIME

<->

com.ronri_kobo.Time

C_DATE

<->

com.ronri_kobo.Date

C_TEXT

<->

java.lang.String

C_PICTURE

<->

com.ronri_kobo.Picture

C_BLOB

<->

byte[]

ARRAY BOOLEAN

<->

boolean[]

ARRAY INTEGER

<->

short[]

ARRAY LONGINT

<->

int[]

ARRAY REAL

<->

double[]

ARRAY DATE

<->

com.ronri_kobo.Date[]

ARRAY TEXT

<->

java.lang.String[]

ARRAY PICTURE

<->

com.ronri_kobo.Picture[]

Error Number

-15901

Java session could not be opened

-15902

Old version of 4D

-15903

68K Macintosh is used

-15904

Old version of Mac OS

-15905

Old version of MRJ

-15906

JWorld_xxx.jar was not found


-15920

Java session was not yet opened

-15922

Basic Java classes for JWorld were not found

-15923

Basic Java methods for JWorld were not found

-15924

libJWorld.jnilib was not found

-15925

java.security was not found

-15926

An error occurred when the classpath was set

-15927

Not enough memory for the classpath

-15928

An error occurred when the Java VM thread was created

-15929

Invalid Java VM DLL

-15930

jvm.dll was not found
-15931 Old version of Java VM (In Windows J2SE is required as a Java VM)


-18000

Trial is over

-18001

Invalid license code

-18007

JbyJ_xxx.jar was not found

-18010

Basic Java classes for JbyJ were not found

-18011

Basic Java methods for JbyJ were not found

-18012

Invalid JVM ID


-18021

The plug-in method tried to be executed before executing JbJ Set environment

-18022

Invalid parameters

-18023

Not enough memory-1

-18024

Not enough memory-2

-18025

Not enough memory-3

-18026

The JbyJ Client has already opened connections with JbyJ Servers fully

-18027

Invalid server ID

-18028

Invalid client ID

-18029

Invalid return type(s)


-18101

RemoteException occurred in Java

-18102

NotBoundException occurred in Java

-18103

MalformedURLException occurred in Java

-18104

UnknownHostException occurred in Java

-18105

InterruptedException occurred in Java

-18106

IOException occurred in Java


-18201

The connection was refused by the JbyJ Server

-18202

The JbyJ Server has been already connected from JbyJ Clients fully

-18204

An error occurred in the remote method

Limitations

1

A remote method cannot be passed over 99 parameters.

2

A remote method cannot return over 99 results.

3

Any two-dimensional array cannot be passed and returned between A JbyJ Server and a JbyJ Client.

4

A JbyJ Server refuses the connection from a JbyJ Client which has the same license key code as the JbyJ Server.

5

A JbyJ Server cannot keep over 1024 connections with JbyJ Clients simultaneously.

6

A JbyJ 4D Client (not Java Client) cannot keep over 1024 connections with JbyJ Servers simultaneously.

7

The plug-in names of JbyJ_xxx.bundle and JWorld_xxx.bundle cannot be changed.

Copyright (C) Ronri Kobo, Inc. All rights reserved.