VisiBroker for .NET Developer’s Guide : Configuring properties
Configuring properties
There are three ways to set VisiBroker for .NET properties. These are given below in order of priority, from highest to lowest.
1
Using command-line arguments
2
Setting properties programmatically
3
Using a configuration file
Note
The settings with higher priority override the settings with lower priority. For example, the properties set at the command-line override the properties defined programmatically.
Setting properties at the command line
If you are running a VisiBroker for .NET application from a command prompt, then you may specify VisiBroker for .NET properties as space-delimited key-value pairs, and the key is preceded by a hyphen (-). For example:
Client -ORBInitRef NameService=corbaloc:iiop:1.2@host1:3075/NameService
In the application code, for developers who use the VisiBroker for .NET style API, the command line arguments can be passed into the corresponding version of the Janeva.Remoting.IiopChannel() constructor. For example:
static void Main(string[] args) {
Janeva.Remoting.IiopChannel channel = new Janeva.Remoting.IiopChannel(args);
…
}
For developers using the CORBA style API, pass these arguments to the static ORB.Init() constructor:
static void Main(string[] args) {
CORBA.ORB orb = CORBA.ORB.Init(args);
...
}
For J2EE developers, VisiBroker for .NET supports an equivalent ORB initialization API using J2EE.Naming.InitialContext(). For example, suppose your J2EE server is running on the local host with a Naming Service listening to port 2809. Your client can use the -ORBInitRef style initialization to point to the Naming Service as follows:
Client -ORBInitRef NameService=corbaname:iiop:localhost:2809/NameService
In you application code, you simply pass these arguments to the static J2EE.Naming.InitialContext constructor:
static void Main(string[] args) {
J2EE.Naming.Context context =
J2EE.Naming.InitialContext(args);
…
}
Setting properties programmatically
You can store VisiBroker for .NET properties in a System.Collections.Hashtable object, and pass these to either CORBA.ORB.Init(), J2EE.Naming.InitialContext(), or Janeva.Remoting.IiopChannel(). This provides a cleaner approach to setting VisiBroker for .NET properties than the command-line approach and is useful when the command-line is not available.
The .NET Remoting developer may pass the Hashtable settings into the appropriate version of the Janeva.Remoting.IiopChannel constructor:
static void Main(string[] args) {
System.Collections.Hashtable props = new System.Collections.Hashtable();
props.Add("ORBInitRef",
“NameService=corbaloc:iiop:1.2@host1:3075/NameService”);
props.Add(“janeva.transaction”, true);
Janeva.Remoting.IiopChannel channel =
new Janeva.Remoting.IiopChannel(args. props);
// other code here
…
}
The following CORBA example creates a Hashtable object and sets three properties:
static void Main(string[] args) {
System.Collections.Hashtable props = new System.Collections.Hashtable();
props.Add("ORBInitRef",
“NameService=corbaloc:iiop:1.2@host1:3075/NameService”);
props.Add("janeva.transactions", true);
CORBA.ORB orb = CORBA.ORB.Init(args, props);
// other code here
…
}
For J2EE developers, you may also use a Hashtable to initialize the application:
static void Main(string[] args) {
System.Collections.Hashtable props = new System.Collections.Hashtable();
props.Add("ORBInitRef",
“NameService=corbaloc:iiop:1.2@host1:3075/NameService”);
props.Add("janeva.transactions", true);
J2EE.Naming.InitialContext context = new J2EE.Naming.InitialContext
(props);
// other code here
…
}
Setting properties within a configuration file
VisiBroker for .NET properties can be set by using a configuration file.
Important
The configuration file section <janeva> is renamed to <visinet> in VisiBroker for .NET 7.0 and later versions. However, for backward compatibility with older versions, the section name <janeva> is still supported.
Properly named, the configuration file is loaded automatically. For ASP.NET applications, this is the Web.config file. For other applications, this is the <app_assembly_name>.exe.config file located in the same directory where the <app_assembly_name>.exe is.
Note
In Microsoft Visual Studio .NET you must add a file called app.config to your project to get the appropriately named XML configuration file included in your build.
The example below shows a sample configuration file.
<configuration>
<configSections>
<section name="visinet" type="Janeva.Settings, Borland.Janeva.Runtime"/>
</configSections>
<visinet>
<transactions enabled="true"/>
<server defaultPort="10000">
<remoting enabled="true"/>
</server>
</visinet>
</configuration>
Notice that all of the VisiBroker for .NET settings are grouped under the <visinet> section in the configuration file. Since the VisiBroker for .NET settings are not part of the standard .NET configuration XML, it is important to instruct the .NET runtime to read the <visinet> XML. This is achieved by adding the <configSections> section as it is demonstrated in the example above.
VisiBroker for .NET property descriptions
Each VisiBroker for .NET property has a counterpart setting in the configuration file. The following sections describe each VisiBroker for .NET property and the corresponding configuration file setting in detail.
Resolving the Naming Service
The following property is used to resolve the Naming Service.
ORBInitRef
Type: string
Default value: none
XML:
<naming url="NameService=URL" />
Each application server has its own URL syntax as shown in the following table.
Application server
Naming Service URL format
WebLogic 7 or 8
corbaloc::localhost:7001/NameService
IBM WebSphere 5
corbaname:iiop:localhost:2809/NameServiceServerRoot
Oracle's 0C4J:
corbaloc:iiop:1.2@localhost:5555/NameService
Sybase
corbaloc:iiop:1.2@localhost:9000/NameService
Note also that the default port number may vary for your deployment.
Note
Resolving the naming service for VisiBroker is automatic (based on OSAgent), so this configuration is optional for VisiBroker. Other application servers require this configuration.
Examples
To resolve the Naming Service using the command line the argument should be in the following format:
> client -ORBInitRef NameService=corbaloc::localhost:7001/NameService
The property setting in the configuration file would resemble the following example.
<visinet>
<naming url=”corbaloc::localhost:7001/NameService” />
</visinet>
Licensing property
This property is configured to enable the VisiBroker for .NET runtime to locate the license if necessary.
janeva.license.dir
Set the path to the directory where the VisiBroker for .NET license file is located. The path can be absolute or relative to the current directory.
Type: string
Default value: none
XML:
<license dir=”path” />
Example
The following example sets the janeva.license.dir property in a configuration file.
<visinet>
<license dir=”C:\Micro Focus\VisiBroker\” />
</visinet>
Transactions properties
These properties are configured to enable VisiBroker for .NET transaction support.
janeva.transactions
Set this property to true to enable support of the client-demarcated transactions. Keep in mind that it is impossible to start a new transaction without turning this feature on. Namely, the orb.ResolveInitialReferences("TransactionCurrent") call will fail if transactions are not enabled.
This feature is disabled by default, as, when enabled, it adds an additional performance overhead during a remote invocation.
Type: boolean [true | false]
Default value: false
XML:
<transactions enabled=”value” />
Note
If the <transactions> section is present in the configuration file, and the enabled attribute is missing, the default VisiBroker for .NET behavior is to enable transactions.
Example
The following example configurations set the janeva.transactions property to true.
<visinet>
<transactions enabled=”true” />
</visinet>
<visinet>
<transactions />
</visinet>
janeva.transactions.factory.url
This URL points to a transaction service Current factory.
Type: string
Default value: none
XML:
<transactions>
<factory url=”corbaloc::URL” />
</transactions>
Example
The following example configuration sets the janeva.transactions.factory.url property.
<visinet>
<transactions enabled=”true”>
<factory url=”corbaloc::localhost:6666/TransactionFactory” />
</transactions>
</visinet>
Server-side properties
These properties are used to configure VisiBroker for .NET server-side support.
janeva.server.defaultPort
This property sets the port on which a VisiBroker for .NET server listens to for IIOP requests. The value 0 (zero) means that the system will pick a random port number.
Type: integer
Default value: 0 (zero)
XML:
<server defaultPort=”value”>
janeva.server.remoting
This property is configured when using remoting-style callbacks and remoting-style VisiBroker for .NET servers. If set to true, then remoting-style callbacks and remoting-style VisiBroker for .NET servers are enabled.
This feature is disabled by default. When enabled, it adds an additional performance overhead during a remote invocation.
Type: boolean [true | false]
Default value: false
XML:
<server><remoting enabled=”value” /></server>
Example
The following example sets the janeva.server.port and the janeva.server.remoting properties in a configuration file.
<visinet>
<server defaultPort=”2809”>
<remoting enabled=”true” />
</server>
</visinet>
Interoperability property
This property is used to configure various VisiBroker for .NET interoperability aspects.
janeva.interop.jvmType
This property controls how VisiBroker for .NET writes certain data types on the wire. It specifies the JVM on the receiving side of the outgoing communication. This is pertinent when communicating with a server running on Java. When communicating between a .NET client and .NET server this property must be set to the same value on both sides.
Type: integer [1|2|3]
Default value: 1
XML:
<interop jvmType=”value” />
Note that the marshaling format for various data types evolves over time as the JDK changes. In order for VisiBroker for .NET to be able to write such changing data types, this flag can be used to indicate which type of VM you are inter-operating with.
Currently there are three valid setting for this flag:
1
A value of 1 indicates that you are using a version 1.1, 1.2 or 1.3 JVM.
2
A value of 2 indicates that you are using a version 1.4.0 or 1.4.1 JVM
3
A value of 3 indicates that you are using a version 1.4.2 or later JVM.
The main difference between JVM Type 1 and 2 is the format for writing an instance of:
java.lang.Random
java.math.BigDecimal
java.math.BigInteger
This format changed in JDK version 1.4.0, and if you need to send such data from a VisiBroker for .NET process to a Java process, you must set this flag appropriately.
The main difference between JVM Type 2 and 3 is the format for writing an instance of:
java.util.Vector
java.util.Stack
This format changed in JDK version 1.4.2, and if you need send such data from a VisiBroker for .NET process to a Java process, you must set this flag appropriately.
A few notes on JVM interoperability:
•
The janeva.interop.jvmType property only affects the write side of VisiBroker for .NET.
•
The VisiBroker for .NET read side always supports all JVMs. So, it is possible to receive Random, Vector, and Stack instances from J2EE applications running on any JVM irrespective of the setting for the jvmType flag. Only when the VisiBroker for .NET process needs to send such objects to a J2EE application will the jvmType need to be specified.
Example
The following example sets the janeva.interop.jvmType property in a configuration file.
<visinet>
<interop jvmType=”2”/>
</visinet>
Security properties
These properties are used to configure VisiBroker for .NET security support.
janeva.security
Set this property to true to enable VisiBroker for .NET security support.
This feature is disabled by default. When enabled, it adds an additional performance overhead during a remote invocation.
Type: boolean [true | false]
Default value: false
XML:
<security enabled=”value”/>
Note
If the <security> section is present in the configuration file, and the enabled attribute is missing, the default VisiBroker for .NET behavior is to enable security.
janeva.security.username
This property configures the user name for the security identity passed to the server-side for authentication. This property is used in conjunction with the janeva.security.password property.
Type: string
Default value: none
XML:
<security><identity><username>value</username></identity></security>
janeva.security.password
Specifies the password in the clear text format.
Type: string
Default value: none
XML:
<security>
<identity>
<password>value</password>
</identity>
</security>
janeva.security.realm
This is the authentication realm to be used in conjunction with the user name and password elements in the security identity configuration. By default, users belong to the security realm called default. This property should be set when using an authentication realm other than a realm called default.
Type: string
Default value: default
XML:
<security>
<identity>
<realm>value</realm>
</identity>
</security>
janeva.security.certificate
This property sets the certificate used for authentication. The expected value is a string representing the friendly name of the certificate located in the Windows Certificate Store.
Type: string
Default value: none
XML:
<security><identity><certificate>value</certificate></identity></security>
Examples
The following example sets the janeva.security.username, janeva.security.password and janeva.security.realm properties for the security identity in a configuration file.
<visinet>
<security enabled=”true”>
<identity>
<username>admin</username>
<password>foobar</password>
<realm>MyRealm</realm>
</identity>
</security>
</visinet>
The following example sets the janeva.security.certificate property for the security identity in a configuration file.
<visinet>
<security enabled=”true”>
<identity>
<certificate>joeshopper</certificate>
</identity>
</security>
</visinet>
Server-side security properties
These properties are used to configure VisiBroker for .NET server-side security.
janeva.security.server
Set this property to true to enable VisiBroker for .NET server-side security support.
This feature is disabled by default, as, when enabled, it adds an additional performance overhead during a remote invocation.
Type: boolean [true | false]
Default value: false
XML:
<security>
<server enabled=”value”/>
</security>
Note
If the <security><server> section is present in the configuration file, and the enabled attribute is missing, the default VisiBroker for .NET behavior is to enable server-side security.
janeva.security.server.defaultPort
Configures the port to be used for SSL over IIOP.
Type: integer
Default value: none
XML:
<security>
<server defaultPort=”value”/>
</security>
janeva.security.server.certificate
This property specifies the friendly name of the certificate. If a certificate is specified in this section, then it will be used to identify the server peer of the SSL connection. Note, that if value for this setting is not provided, the VisiBroker for .NET runtime will try to use a certificate provided in the janeva.security.certificate setting. If neither of these settings is specified, VisiBroker for .NET runtime considers this as a bad configuration and fails to initialize.
Type: string
Default value: none
XML:
<security>
<server>
<certificate>value</certificate>
</server>
</security>
Example
The following example sets the server-side security properties in a configuration file.
<visinet>
<security>
<server enabled=”true” defaultPort=”15000”>
<certificate>Book Store</certificate>
</server>
</security>
</visinet>
Firewall property
This property is used to enable the VisiBroker for .NET firewall support.
janeva.firewall
Enables support of the high-level firewall gateway such as VisiBroker Gatekeeper.
This feature is disabled by default, as, when enabled, it adds an additional performance overhead during a remote invocation.
Type: boolean [true | false]
Default value: false
XML:
<firewall enabled=”value”/>
Note
If the <firewall> section is present in the configuration file, and the enabled attribute is missing, the default VisiBroker for .NET behavior is to enable the firewall.
Example
The following example sets the janeva.firewall property in a configuration file.
<visinet>
<firewall enabled=”true”/>
</visinet>
Portable Interceptor property
This property is used to configure the portable interceptor.
janeva.orb.init
Specifies the portable interceptor that needs to be loaded by the ORB. If the portable interceptor is part of the same assembly containing the main class, then you can just specify the class name. If the portable interceptor is part of an assembly outside of the assembly containing the main class, then you need to specify the strongly-named assembly name. You may specify as many portable interceptors as you wish.
Type: string
Default value: none
XML:
<orb>
<init type=”value”/>
</orb>
Example
The following example sets the janeva.orb.init property in a configuration file.
<visinet>
<orb>
<init type="MyInterceptor, MyInterceptorAssembly, version=1.2.3.4,
culture=neutral, publicKeyToken=xxxx"/>
<init type="MyInterceptor2”/>
</orb>
</visinet>
VisiBroker Smart Agent properties
These properties are configured when you are using the Smart Agent (OSAgent) for object registration and lookup.
janeva.agent
This property can be used to disable the Smart Agent.
Type: boolean [true | false]
Default value: false
XML:
<agent enabled=”value”/>
janeva.agent.port
This property sets the port used by the Smart Agent.
Type: integer
Default value: 14000
XML:
<agent port=”value”/>
janeva.agent.addr
This property specifies the physical location of the Smart Agent, either by IP address or hostname. If not provided, VisiBroker for .NET will look for any Smart Agent on the network with the proper port during the ping. Providing a host address will reduce network traffic, as VisiBroker for .NET will ping the Smart Agent on the provided host address and port.
Type: string
Default value: none
XML:
<agent addr=”value”/>
Example
The following example configuration file sets the janeva.agent janeva.agent.port and janeva.agent.addr properties.
<visinet>
<agent enabled=”true” port="14001" addr="localhost.localdomain.com"/>
</visinet>
Setting VisiBroker properties
VisiBroker for .NET supports all of the properties originally introduced in the VisiBroker line of products. Among these properties are the settings used to fine-tune the firewall support. In a configuration file you can specify the VisiBroker properties as key-value attributes in the <vbroker> section.
The following example show how to set some VisiBroker GateKeeper properties in a configuration file.
<visinet>
<firewall enabled=”true”/>
<vbroker
vbroker.orb.alwaysProxy=”true”
vbroker.orb.gatekeeper.ior=”ior:…”
/>
</visinet>