libOrcaIce
[Libraries]

Customizes Ice API for Orca. More...

Customizes Ice API for Orca.

Development status

Used by all components, API is fairly stable.

Overview

This library aims at simplifying Orca component development. It provides several helper classes to use and derive from and several functions to use. In doing so we make unavoidable assumptions about how Ice is going to be used in Orca components. If your component cannot live with these constraints you can always go back to using Ice directly (it's not much more work).

Header file:

#include <orcaice/orcaice.h>

Contents:

• Full list of functions and classes
• Class usage
• Function usage
• Complete list of configuration properties

Class usage

Here's what our stand-alone component looks like. In this figure and the one below, white color stands for standard Ice objects which we don't modify, e.g. the Communicator -- the Ice run-time object. Gray color stands for the objects which come with libOrcaIce and used unmodified by component developers. Cream color stands for component-specific code, written by component developers.

Here's what an IceBox service looks like. The main idea is to have the guts of the component used unmodified in both stand-alone and application server environment.

Note that 'Component1' code is identical in both cases -- that's a big time saver!

Function usage

The functions described here are very high-level. They are intended as one-line wrappers which work in typical situations. If your usage does not fit the pattern, no worries: just look how they are implemented, copy the code into your program and modify it as needed.

In the discussion below, we assume here that the library functions are called from inside a class derived from orcaice::Component. You can see more output from libOrcaIce by setting orcaice::Tracer verbosity for info, warning, and error to 2.

To create a Provided Interface

Make an instance of your object implementation and initialize it using information in the config file.

Ice::MyInterfacePtr obj = new MyInterfaceI;
orcaice::createInterfaceWithTag( context(), obj, "MyConfigFileTag" );

The interface tag in this example is "MyConfigFileTag". The function context() summarizes the context of your component (pointers to Communicator, Adapter, etc.). The function orcaice::createInterfaceWithTag adds the newly created interface implementation to the component's adapter, thereby making it reachable over the network.

To start publishing to IceStorm

Let's start sending updates of object type orca::MyObject. The config file tag for this interface is "MyConfigFileTag".

orca::MyInterfaceConsumerPrx publisher;
orcaice::connectToTopicWithTag <orca::MyObjectConsumerPrx> ( context(), publisher, "MyConfigFileTag" );

Use this function to connect to the IceStorm server and get a proxy to the "consumer of information". We will publish information by pushing data to the consumer. Note that you don't create the proxy itself (using keyword new), the function does everything for you.

To connect to a Required Interface

Now let's connect to a remote interface. We first create a proxy of the right type (so we can call its remote operations). The interface tag here is "MyConfigFileTag". Note that you don't create the proxy itself (with new), the function does everything for you.

orca::YourObjectPrx yourObjectPrx;
orcaice::connectToInterface<orca::YourObjectPrx>( context(), yourObjectPrx, "MyConfigFileTag" );

To subscribe to an IceStorm topic

There's no corresponding function in libOrcaIce because, normally, you call the subscribe() operation on an interface which publishes the data so you don't actually talk to the IceStorm server directly.

Complete list of configuration properties

The following properties are assigned defaults unless they are configured explicitely:

• IceStorm.TopicManager.Proxy (string)
  • Default: "IceStorm/TopicManager:default -t 8000 -p 10000"

• [ComponentTag].AdapterId (string)
  • Default: "[platform name]/[component name]"

• [ComponentTag].Endpoints (string)
  • Communication endpoints used by component interfaces.
  • Default: "tcp -t 5000"
  • Note on usage with IceGrid: if this property is left undefined in the XML application descriptor, IceGrid will fill it with 'default' in the generated config file. This means that the Orca default will never be envoked.

• Ice.Admin.Endpoints (string)
  • Communication endpoints used by component "standard" interfaces, i.e. Home, Tracer, Status.
  • Default: "tcp -t 5000"
  • Note on usage with IceGrid: if this property is left undefined in the XML application descriptor, IceGrid will fill it with 'tcp -h 127.0.0.1' in the generated config file. This means that the Orca default will never be envoked.

Component and Application properties.

• Orca.Component.RequireRegistry (bool)
  • When component activates it tries to register its adapter with the Registry. If it cannot connect (e.g. Registy is not running) it gets an exception. When indirect binding (using names) is used this makes a component with provided interfaces useless because nobody can connect to it. In this case requiring registry makes sense and the component should exit at this point. There are cases however when you may want to ignore this and continue with the startup.
  • Default: 1

• Orca.Component.EnableTracer (bool)
  • Enables Orca-standard Tracer interface which allows remote access to component's execution traces. This property overrides the default set in code.
  • Default: component-specific, set in code.

• Orca.Component.EnableStatus (bool)
  • Enables Orca-standard Status interface which allows remote access to component's status information. This property overrides the default set in code.
  • Default: component-specific, set in code.

• Orca.Component.EnableHome (bool)
  • Enables Orca-standard Home interface which allows remote access to component's interface information. This property overrides the default set in code.
  • Default: component-specific, set in code.

• Orca.Component.EnableProperties (bool)
  • Enables Ice-standard Properties interface which allows remote read access to all component properties.
  • Default: 1

• Orca.Component.EnableProcess (bool)
  • Enables Ice-standard Process interface which allows remote shutdown of the component.
  • Default: 0

• Orca.PrintProperties (bool)
  • Print out all properties passed to the component? Includes hardwired defaults, global settings, properties from the component configuration file, and command line options.
  • Default: 0

• Orca.Component.PrintProperties (bool)
  • If this property is set to 1, all properties are printed during the startup procedure. Useful for debugging.
  • Default: 0

• Orca.Component.PrintContext (bool)
  • If this property is set to 1, all Context settings are printed during the startup procedure. Useful for debugging.
  • Default: 0

• Orca.Component.PrintStarted (bool)
  • If this property is set to 1, a statement is printed to standard output when component initialization is complete.
  • Default: 0

• Orca.Application.CallbackOnInterrupt (bool)
  • This is an advanced property. Default value should be good for most cases. The alternative is to request ShutdownOnInterrupt.
  • Default: 1

Properties for individual standard interfaces.

• Orca.Status.RequireIceStorm (bool)
  • If this property is set to 1, the component will quit if its Status interface cannot connect to IceStorm.
  • Default: 0

• Orca.Status.PublishPeriod (int)
  • Maximum interval between updates sent by the Status interface.
  • Units: seconds
  • Default: 30

• Orca.Status.StallTolerance.Multiplicative (double)
  • Multiplicative tolerance factor applied by Status to the maximum heartbeat interval of each subsystem in deciding when to declare a subsystem stalled.
  • Units: none
  • Default: 1.5

• Orca.Status.StallTolerance.Additive (double)
  • Additive tolerance factor added by Status to the maximum heartbeat interval of each subsystem in deciding when to declare a subsystem stalled.
  • Units: seconds
  • Default: 0.1

• Orca.Tracer.RequireIceStorm (bool)
  • If this property is set to 1, the component will quit if its Tracer interface cannot connect to IceStorm.
  • Default: 0

• Orca.Tracer.Filename (string)
  • The name of the file to which the Tracer will write the traces enabled by *ToFile properties.
  • Default: "[ComponentName]_trace.txt"

• Orca.Tracer.Timestamp (bool)
  • When enabled, prepends human-readable time stamp to all traces.
  • Default: 1

Tracing and warnings.

• Orca.Warn.DefaultProperty (bool)
  • If this property is set to 1, a warning is printed every time a default property is used when calling *WithDefault() functions. e.g. orcaice::getPropertyAsIntWithDefault().
  • Default: 1

• Orca.Warn.FactoryProperty (bool)
  • If this property is set to 1, a warning is printed when a factory default is used. This applies only during component initialization.
  • Default: 0

A sample configuration file which sets all parameters to sensible defaults is shown here.

# Ice config
Ice.Default.Locator=IceGrid/Locator: default -p 12000
#Ice.Default.Locator=IceGrid/Locator: default: default -h host.xxx.xxx.xxx -p 12000

# Orca config
Orca.Component.RequireRegisty=0
Orca.Component.PrintProperties=0
Orca.Component.PrintContext=0
Orca.Component.PrintStarted=0

Orca.Status.RequireIceStorm=0
Orca.Tracer.RequireIceStorm=0

# Orca warnings
Orca.Warn.DefaultProperty=1
Orca.Warn.FactoryProperty=0

# Orca Tracer config
Orca.Tracer.Filename=orca_component_trace.txt
Orca.Tracer.InfoToDisplay=1
Orca.Tracer.InfoToNetwork=0
Orca.Tracer.InfoToLog=0
Orca.Tracer.InfoToFile=0
Orca.Tracer.WarningToDisplay=1
Orca.Tracer.WarningToNetwork=0
Orca.Tracer.WarningToLog=0
Orca.Tracer.WarningToFile=0
Orca.Tracer.ErrorToDisplay=10
Orca.Tracer.ErrorToNetwork=0
Orca.Tracer.ErrorToLog=0
Orca.Tracer.ErrorToFile=0
Orca.Tracer.DebugToDisplay=0
Orca.Tracer.DebugToNetwork=0
Orca.Tracer.DebugToLog=0
Orca.Tracer.DebugToFile=0
Orca.Tracer.Timestamp=1

Responsible Developer

Alex Brooks, Alex Makarenko