Issue 15680: valuetype is missing (rclm-rtf)
Source: Remedy IT (Mr. Johnny Willemsen, jwillemsen(at)remedy.nl)
Nature: Enhancement
Severity: Significant
Summary: The spec lacks the mapping of valuetypes, this should be added
Resolution: Add the revised text as below to the specification
Revised Text: 7.19 Mapping for Valuetypes

An IDL valuetype is mapped on a Ruby class (using the naming conventions described in Section 7.2, “Using Scoped Names,” on page 3) that contains public definitions of the types, constants, operations, attributes and state members defined as part of the valuetype. 
The CORBA::ValueBase type is mapped on the Ruby mixin module CORBA::ValueBase which is included in every concrete valuetype class.

All operations defined as part of the valuetype (or supported interfaces) are declared with a default implementation which throws a runtime exception stating the operation is unimplemented.
When a valuetype defines (or supports) operations the application developer should override the default implementation. In Ruby this can be done either in a class derived directly or indirectly from the generated valuetype class (in case multiple valuetype implementations are possible) or by “reopening” the generated valuetype class.

The valuetype null value is mapped to the Ruby nil value.

7.19.1 Valuetype data (state) members

The Ruby mapping for valuetype data members follows the same rules as the Ruby mapping for struct members. Public state members are mapped to public accessors Ruby valuetype (base) class, and private state members are mapped to protected accessors (so that derived concrete classes may access them).

For example:

// IDL
typedef octet Bytes[64];
struct S { ... };
interface A { ... };

valuetype Val {
	public Val t;
	private long v;
	public Bytes w;
	public 	string x;
	private S y;
	private A z;
};

could be implemented in Ruby as

# Ruby 
class S
	...
end

module A
	…
end

class Val
	include CORBA::ValueBase
	…
	attr_accessor :t
	attr_accessor :w
	attr_accessor :x

	protected
		attr_accessor :v
		attr_accessor :y
		attr_accessor :z
		...
end

7.19.2 Valuetype operations

All operations declared on a valuetype are mapped on public methods with a default implementation which throws a runtime exception stating the operation is unimplemented.

When a valuetype declares operations the application developer should override the default implementation. In Ruby this can be done either in a class derived directly or indirectly from the generated valuetype class (in case multiple valuetype implementations are possible) or by “reopening” the generated valuetype class.

For example:

// IDL
valuetype BaseNode {
	short op1();
	long op2(in BaseNode node);

	public string name;
	private long id;
};

could be implemented in Ruby as

# Ruby
class BaseNode < CORBA::ValueBase
	include CORBA::ValueBase
	…
	def op1
		raise RuntimeError...
	end
	def op2(node)
		raise RuntimeError...
	end

	attr_accessor :name
	protected
		attr_accessor :id
end

7.19.3 Value Boxes

A boxed type IDL valuetype declaration is mapped on a Ruby class that contains a single, public, Ruby accessor implementation for a standard member of the boxed type named value.
In essence this class provides a very simple container for the boxed type allowing null values to be passed as interface arguments for these types.

To fulfill the ValueBase interface all value box classes include the Ruby mixin module CORBA::Portable::BoxedValueBase which is derived from the Ruby CORBA::ValueBase module.

For example:

// IDL
valuetype string BoxedString;

could be implemented in Ruby as

# Ruby
class BoxedString
	include CORBA::ValueBase
	…
	attr_accessor :value
end

When declaring value boxes as argument or return types for interface operations (or attribute accessor and modifier methods) the Ruby implementation provides implicit conversion of the underlying boxed type to (for in arguments) or from (for out arguments and return values) the value box type:

// IDL
valuetype string BoxedString;
valuetype long BoxedLong;

interface Foo {
	void echo(in BoxedString txt);

	attribute BoxedLong count;
};

could be implemented in Ruby as

# Ruby
…
my_foo = Foo._narrow(some_obj_ref)

# passing underlying boxed type works fine
my_foo.echo('Hello too')
my_foo.count = 1
# passing null values too
my_foo.echo(nil)
my_fo.count = nil
# passing actual value box is also possible
bs = BoxedString.new
bs.value = 'Hello'
my_foo.echo(bs)

# return values and out args are always returned as underlying boxed type 
# (or nil for null values)

# returns an integer value (NOT BoxedLong) or nil
the_count = my_foo.count

7.19.4 Abstract Valuetypes

An IDL abstract valuetype is mapped on a Ruby module (using the naming conventions described in Section 7.2, “Using Scoped Names,” on page 3) that contains public definitions of the types, constants, operations and attributes defined as part of the valuetype. 
Abstract valuetypes cannot be instantiated and the mapping on a Ruby module ensures that (as with the interface mapping; 7.4).

As an abstract valuetype has no state members which may need marshaling/demarshaling and cannot be instantiated there are no factory classes generated for abstract valuetypes.

7.19.5 Valuetype inheritance

For an IDL valuetype derived from other valuetypes or that supports interface types the following applies:

Concrete and abstract value base classes are inherited
Supported interfaces are inherited with respect to ancestor type information (is_a semantics) and operations and attributes interfaces; not inherited are object reference semantics 

Valuetype classes inheriting supported interfaces do not inherit object reference semantics like narrowing methods. Also calling any method mapped from an interface inherited operation or attribute will result in a CORBA::NO_IMPLEMENT exception being thrown by default.
Applications can provide overridden implementations by either deriving an application specific valuetype class or by “reopening” the generated class.

In case of a valuetype supporting an interface the IDL compiler will also generate a servant skeleton in the POA namespace (see 7.25) with the same name as the valuetype class (including scoping). This servant skeleton class inherits from the valuetype class and from the servant classes for the supported interfaces.

For example:

// IDL
interface A {
	void op();
};
valuetype B supports A {
	public short data;
};

could be implemented in Ruby as

# Ruby
# Client side mapping

module A
	...
end

class B
	include CORBA::ValueBase
	…
	def op
		...
	end

	attr_accessor :data
end

# Server side mapping

module POA
	class A
		...
	end

	class B
		…
		include POA::A
		include ::B
	end
end

7.19.6 Valuetype Factories

Valuetype factories are the means by which the ORB is able to instantiate new instances of (possibly user derived) concrete valuetype classes at demarshaling time.

For every concrete valuetype there is an additional factory class generated. The name of the class is formed by appending the suffix “Factory” to the valuetype name. The base class for all factory classes is CORBA::ValueFactory.
The generated factory class implements a default factory method name “_create_default” returning a newly created instance (with default, empty, initialization) of the generated valuetype class. This method is called by the ORB on registered valuetype factories when creating new valuetype instances for the purpose of demarshaling.
Additionally for each factory method defined for a valuetype a default method implementation will be generated (having the name and arguments as specified for the IDL defined factory method) as part of the factory class. The default implementation of these factory methods will throw a runtime exception stating the operation is unimplemented.
Application derived implementations of these factory methods should return a valuetype instance of the corresponding (possibly application derived) valuetype class.

For example:

// IDL
valuetype Coord {
	public double x;
	public double y;

	factory setup(in double x_org, in double y_org);
};

could be implemented in Ruby as:

# Ruby
class Coord
	include CORBA::ValueBase
	...
end

class CoordFactory
	...
	def  _create_default
		Coord.new
	end

	def setup(x_org, y_org)
		raise RuntimeError...
	end
	...
end

Applications can derive and implement customized value factories by using the generated value factory classes as base class.
To enable the ORB to make use of a value factory for a certain valuetype the application must register an instance of a value factory class through the ORB::register_value_factory class.

For simple valuetypes having only state members (no operations, no attributes and no type specific factory methods), the generated factory class is normally sufficient and needs no derivatives.
The application however, still needs to explicitly register a value factory instance with the ORB.

Valueboxes constitute a special case of state-only valuetypes and as such never require derived value factories or even factory registration.
Default value factory instances for every IDL defined valuebox type will be implicitly registered with the ORB.

7.19.7 Custom Marshaling

Valuetypes declared to have custom marshaling follow the same Ruby mapping rules as for normal (non-custom declared) valuetypes except for the following:

“custom” valuetype classes do not get marshaling and demarshaling code generated but instead implement the Ruby mapping of the interface of CORBA::CustomMarshal abstract valuetype which declares the marshal and unmarshal methods

The application should provide implementations for the marshal and unmarshal methods of each custom valuetype.

The CORBA::DataOutputStream and CORBA::DataInputStream arguments of these methods are mapped on Ruby classes providing Ruby mappings for the IDL valuetype operation declarations.

For example:

// IDL
custom valuetype CustomFoo {
	public string name;
	private short id;
};

could be implemented in Ruby as:

# Ruby

class CustomFoo
	…
	attr_accessor :name
	protected
		attr_accessor :id
	public
		def marshal(os)
		...
		end

		def unmarshal(is)
		...
		end
		...
end

class CustomFooImpl < CustomFoo
	…
	def marshal(os)
		os.write_string(self.name)
		os.write_short(self.id)
	end
	def unmarshal(is)
		self.name = is.read_string
		self.id = is.read_short
	end
	...
end

Actions taken:
October 4, 2010: received issue
January 11, 2012: closed issue
Discussion: 


End of Annotations:=====

m: webmaster@omg.org
Date: 04 Oct 2010 02:57:33 -0400
To: <issues@omg.org>
Subject: Issue/Bug Report


*******************************************************************************
Name:            Johnny Willemsen
Employer:        Remedy IT
mailFrom:        jwillemsen@remedy.nl
Terms_Agreement: I agree
Specification:   RCLM
Section:         7.19
FormalNumber:    2010-03-02
Version:         1
Doc_Year:        2010
Doc_Month:       March
Doc_Day:         01
Page:            16
Title:           valuetype is missing
Nature:          Enhancement
Severity:        Significant
CODE:            3TMw8
B1:              Report Issue


Description:

The spec lacks the mapping of valuetypes, this should be added