orb/invo/corba.h

/*
 * Copyright 2008 Sun Microsystems, Inc.  All rights reserved.
 * Use is subject to license terms.
 *
 *  corba.h
 *
 */

#ifndef _CORBA_H
#define	_CORBA_H

#pragma ident	"@(#)corba.h	1.102	08/07/05 SMI"

//
// $XConsortium$
//

//
// Copyright (c) 1993-94 Silicon Graphics, Inc.
// Copyright (c) 1993-94 Fujitsu, Ltd.
//
// Permission to use, copy, modify, distribute, and sell this software and
// its documentation for any purpose is hereby granted without fee, provided
// that (i) the above copyright notices and this permission notice appear in
// all copies of the software and related documentation, and (ii) the names of
// Silicon Graphics and Fujitsu may not be used in any advertising or
// publicity relating to the software without the specific, prior written
// permission of Silicon Graphics and Fujitsu.
//
// THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND,
// EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
// WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
//
// IN NO EVENT SHALL SILICON GRAPHICS OR FUJITSU BE LIABLE FOR
// ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND,
// OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
// WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF
// LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
// OF THIS SOFTWARE.
//

#ifdef	linux
// Dependencies: corba.h needs Ix_Forward from ix.h, which includes
// ix_tmpl.h which uses CORBA:: defined in corba.h
// So need to include ix.h first, which will define Ix_Forward.h
// then include corba.h, then include ix_tmpl.h
// So ix.h needs to be included first.
#include <orb/invo/ix.h>
#endif	/* linux */

#include <orb/idl_datatypes/sequence.h>
#include <orb/invo/ix_tmpl.h>
#include <orb/invo/ix.h>
#include <orb/invo/argfuncs.h>
#include <orb/member/Node.h>
#include <orb/idl_datatypes/idl_strings.h>
#include <orb/idl_datatypes/string_seq.h>
#include <orb/idl_datatypes/interfaceseq.h>

#if defined(_KERNEL_ORB) && !defined(_KERNEL)
#define	UNODE
#else
#undef	UNODE
#endif

#if (SOL_VERSION >= __s10) && !defined(UNODE)
#include <sys/zone.h>
#define	PHYSICAL_CLUSTER_ID 0
#endif

//
// nil - represents an object reference to no object.
//
#ifndef nil
#define	nil 0
#endif

// Forward declarations.
class InterfaceDescriptor;
class MarshalStream;
class service;
class generic_proxy;
class inf_descriptor;

template<class A, class A_ptr> class _A_var_;
template<class A, class A_ptr> class _A_field_;
template<class A, class A_ptr> class _A_out_;

template<class T, class T_ptr> class _T_out_;

template<class SEQUENCE_TYPE, class ELEMENT_TYPE> class _ManagedSeq_;

class _string_seq;

//
// The CORBA namespace (defined as a class since namespaces are not
// currently supported) provides common definitions for the IDL C++ mapping.
//
class CORBA {
public:
	class Environment;

	typedef char					*String_ptr;
	typedef _string_field				String_field;
	typedef _string_var				String_var;
	typedef _string_out				String_out;
	typedef _string_seq				StringSeq;
	typedef _T_out_<StringSeq, StringSeq *>		StringSeq_out;
	typedef _ManagedSeq_<StringSeq, String_field>	StringSeq_var;

	_Ix_Forward(Object)

	static bool is_nil(Object_ptr object_p);
	static void release(Object_ptr object_p);

	_Ix_Forward(Type)

	//
	// A type id in memory is a pointer to the variable-length
	// representation. Current implementation uses MD5, future
	// implementations may include DCE UUID. Both of these are
	// 128bits in length.
	//
	typedef type_identifier_p TypeId;

	//
	// We use MD5 encoding for typeids. This is a 128bit digest.
	//
	typedef uint32_t MD5_Tid[4];

	//
	// The IDL compiler will generate a function like the following
	// for each interface:
	//	type_info_t *<interface_name>::_get_type_info(int N)
	// It returns a pointer to an internal data structure that
	// represents the interface type information for the given version.
	//
	struct type_info_t;

	// Returns a proxy object of the given type.
	static Object_ptr create_proxy_obj(type_info_t *tp, handler *hp);

	//
	// These types are for the _generic_method().
	//
	typedef _FixedSeq_<uint8_t> octet_seq_t;
	typedef _T_out_<octet_seq_t, octet_seq_t *> octet_seq_t_out;
	typedef _ManagedSeq_<octet_seq_t, uint8_t> octet_seq_t_var;
	typedef _Ix_InterfaceSeq_<Object, Object_field, Object_ptr>
	    object_seq_t;
	typedef _T_out_<object_seq_t, object_seq_t *> object_seq_t_out;
	typedef _ManagedSeq_<object_seq_t, Object_field> object_seq_t_var;

	//
	// All objects support CORBA::Object operations, which
	// includes access to an object's type and holding or
	// releasing a reference to the object.
	//
	// Warning: the code generated by the IDL compiler and the
	// implementation code for handlers assume CORBA::Object and the
	// IDL interface class definitions contain no data members
	// (only methods and type definitions). Data definitions are
	// contained in the adaptor and proxy templates which inherit
	// from the IDL class.
	//
	class Object {
	public:
		//
		// Only those routines which absolutely know there is
		// a handler down there should use this.
		//
		virtual handler		*_handler() = 0;

		// _unreferenced has to be defined before instantiating
		virtual void		_unreferenced(unref_t cookie = 0) = 0;

		bool			_equiv(Object_ptr object2_p);

		uint_t			_hash(uint_t sz);

		// Return a pointer to the deep C++ object (or proxy).
		virtual void		*_this_ptr();

		// Return a pointer to the deep C++ object (or proxy).
		Object_ptr		_this_obj();

		//
		// Return the compiled-in InterfaceDescriptor pointer for
		// this class (i.e., the type of the actual C++ structure
		// for this pointer).
		//
		virtual InterfaceDescriptor	*_interface_descriptor();

		//
		// Return the dynamic InterfaceDescriptor pointer for
		// this class (i.e., the type of the object for this
		// CORBA reference).  This is the same as the above for
		// server-side implementation objects but can differ
		// for proxy objects.
		//
		virtual InterfaceDescriptor	*_deep_type();

		// Return a pointer to the C++ proxy object.
		virtual generic_proxy	*_this_component_ptr();

		//
		// Convenience functions,
		// might be better to call the handler operations directly
		//
		bool			_is_local();

		// Increase the reference count for this object.
		static Object_ptr	_duplicate(Object_ptr);

		// Returns the nil object pointer.
		static Object_ptr	_nil();

		//
		// This is a built-in generic method available for passing
		// information. It is up to the caller and server object
		// to understand the format of the data.
		//
		virtual void _generic_method(octet_seq_t &data,
		    object_seq_t &objs, Environment &_environment);

		//
		// Return the version number of the given object or -1.
		// Note this routine is not virtual on purpose. If you
		// call CORBA::Object::_version(p), you will get the
		// version of CORBA::Object that p supports. Since all
		// objects support CORBA::Object, -1 can only be returned
		// if p is nil. But, if A::_version(p) is called, -1
		// is returned if the object doesn't support interface A.
		//
		static int		_version(Object_ptr);

		// Return the type info for CORBA::Object.
		static type_info_t	*_get_type_info(int v);

		// Returns true if the object supports the given type.
		bool			_supports_type(type_info_t *tp);

		//
		// Object constructor and destructor are public so that one can
		// have local (stack-based) objects.
		//
		Object();
		virtual ~Object();

	private:
		// Disallow assignments, pass by value.
		Object(const Object &);
		Object &operator = (const Object &);
	};

	//
	// TCKind is an enumeration of the different categories of types.
	//
	enum TCKind { tk_null, tk_void,
		tk_short, tk_long, tk_ushort, tk_ulong,
		tk_float, tk_double, tk_boolean, tk_char,
		tk_octet, tk_any,
		tk_TypeCode, tk_Principal, tk_objref,
		tk_struct, tk_union, tk_enum, tk_string,
		tk_sequence, tk_array,
		tk_longlong, tk_ulonglong,
		tk_except, tk_module
	};

	//
	// Base classes for exceptions
	//
	enum CompletionStatus { COMPLETED_YES, COMPLETED_NO, COMPLETED_MAYBE };

	//
	// ExceptionStatus identifies the result of an invocation.
	//	NO_EXCEPTION  signifies successful completion.
	// There are two fundamental types of error:
	//	SYSTEM_EXCEPTION is thrown by orb/transport/HA infrastructure.
	//	USER_EXCEPTION is thrown by other code.
	// Both types involve marshal/unmarshal operations when the exception
	// is passed over the wire.
	//
	// Other values identify intermediate states:
	// UNINITIALIZED	- result not yet available.
	// RETRY_EXCEPTION	- the operation should be retried.
	// LOCAL_EXCEPTION	- system exception occurred on local node.
	// REMOTE_EXCEPTION	- shows that an exception occurred on a
	//	remote server. The msg contains either a user or system
	//	exception.
	//
	enum ExceptionStatus { UNINITIALIZED = -1, NO_EXCEPTION,
			USER_EXCEPTION, SYSTEM_EXCEPTION, LOCAL_EXCEPTION,
			RETRY_EXCEPTION, REMOTE_EXCEPTION };

	//
	// enum representation for exceptions.
	//
	enum exception_enum_t {
		user_exception = 0,
		system_exception = 1,
		bad_param = 2,
		comm_failure = 3,
		inv_objref = 4,
		wouldblock = 5,
		retry_needed = 6,
		primary_frozen = 7,
		version_exception = 8,
		ctx_eaccess = 9,
		ns_eperm = 10
	};

	//
	// Exception is the parent class for objects representing errors.
	// A virtual destructor exists because some of the user exceptions
	// need to do something special.
	//
	class Exception {
	public:
		virtual void		_put(service &) const = 0;
		virtual void		print_exception(char *) = 0;
		virtual bool		is_system_exception() = 0;

		virtual			~Exception();

		bool			type_match(Exception *exceptp);
		TypeId			get_typeid();
		uint_t			_major() const;
		const char		*_name() const;

		exception_enum_t	exception_enum();

	protected:
		Exception(uint_t major, TypeId new_tid, const char *name);

		TypeId			tid;
		uint_t			_major_;
		const char		*_name_;

	private:
		// Disallow constructor that does not do proper initialization
		Exception();
	};

	class SystemException : public Exception {
	public:
		SystemException(uint_t major, uint_t minor,
		    CompletionStatus compstatus);

		bool			is_system_exception();

		static SystemException	*_exnarrow(Exception *);

		virtual void		print_exception(char *);

		void			_put(service &) const;
		void			_put(MarshalStream &) const;

		uint_t			_minor();
		void			_minor(uint_t mi);

		void			completed(CompletionStatus cs);
		CompletionStatus	completed();

	protected:
		uint_t			_minor_;
		CompletionStatus 	_completed_;

	private:
		// Disallow constructor that does not do proper initialization
		SystemException();
	};

	class UserException : public Exception {
	public:
		bool			is_system_exception();
		static UserException	*_exnarrow(Exception *);
		static void		*_try_cast(Exception *, TypeId);
		void			_put(service &) const;
		virtual void		print_exception(char *);

	protected:
		UserException(uint_t major, TypeId new_tid, const char *name);

		// stubs generate code that requires pass by value
		//	UserException(const UserException &);

	private:
		// Never create a plain UserException
		UserException();

		// Disallow assignments
		UserException &operator = (const UserException &);
	};

	//
	// List of System Exceptions.
	//

	//
	// Bad Parameter.
	// The exception may contain further info about what was wrong
	// with the parameter.
	//
	class BAD_PARAM : public SystemException {
	public:
		BAD_PARAM(uint_t minor, CompletionStatus completed);

		virtual			~BAD_PARAM();

		static BAD_PARAM	*_exnarrow(Exception *exceptp);
	};

	//
	// The destination is not reachable.
	// Typically this means that the node containing the server is down.
	//
	class COMM_FAILURE : public SystemException {
	public:
		COMM_FAILURE(uint_t minor, CompletionStatus completed);

		virtual			~COMM_FAILURE();

		static COMM_FAILURE	*_exnarrow(Exception *exceptp);
	};

	//
	// Invalid Object Reference
	//
	class INV_OBJREF : public SystemException {
	public:
		INV_OBJREF(uint_t minor, CompletionStatus completed);

		virtual			~INV_OBJREF();

		static INV_OBJREF	*_exnarrow(Exception *exceptp);
	};

	//
	// This exception can be returned only to nonblocking requests.
	// The ORB/transport returns this error whenever it
	// would have blocked for any reason (e.g., memory allocation
	// failures, long-term locks).
	//
	// Note that regular (non-interrupt thread)
	// client/server code would not get this exception,
	// because they would allow blocking.
	// Invocations running in the interrupt thread must use
	// nonblocking semantics.
	//
	// The system uses a server thread to process twoway requests reaching
	// a server on a remote node. Twoway requests always allow blocking.
	// A server processing twoway requests must NEVER generate this
	// exception.
	//
	class WOULDBLOCK : public SystemException {
	public:
		WOULDBLOCK(uint_t minor, CompletionStatus completed);

		virtual			~WOULDBLOCK();

		static WOULDBLOCK	*_exnarrow(Exception *exceptp);
	};

	//
	// This exception is used by the framework to report an error
	// that can be overcome by retrying the operation.
	//
	class RETRY_NEEDED : public SystemException {
	public:
		RETRY_NEEDED(uint_t minor, CompletionStatus completed);

		virtual			~RETRY_NEEDED();

		static RETRY_NEEDED	*_exnarrow(Exception *exceptp);
	};

	//
	// This exception is used by the ha framework to report that the
	// primary has been frozen and that the client should retry the
	// invocation after the service is unfrozen.
	//
	class PRIMARY_FROZEN : public SystemException {
	public:
		PRIMARY_FROZEN(uint_t minor, CompletionStatus completed);

		virtual			~PRIMARY_FROZEN();

		static PRIMARY_FROZEN	*_exnarrow(Exception *exceptp);
	};

	//
	// This exception is thrown when a client tries to call a method
	// and the version of the server object does not support that
	// method.
	//
	class VERSION : public SystemException {
	public:
		//
		// The default constructor should be used to throw
		// the "this function is not implemented" exception.
		//
		// Minor number 0 means deep type doesn't support this method.
		// (usually raised by the client)
		// Minor number 1 means server doesn't implement this method.
		// (usually raised by the server)
		//
		VERSION();
		VERSION(uint_t minor, CompletionStatus completed);

		virtual ~VERSION();

		static VERSION *_exnarrow(Exception *exceptp);
	};

	//
	// This exception is used by the name server software
	// to deny permission to access the real root of the
	// global and lcoal name server
	//
	class CTX_EACCESS : public SystemException {
	public:
		CTX_EACCESS(uint_t minor, CompletionStatus completed);

		virtual			~CTX_EACCESS();

		static CTX_EACCESS	*_exnarrow(Exception *exceptp);
	};

	//
	// This exception used by the name server software. When
	// this exception is raised, it means that the client does
	// not have permission to perform the requested operation.
	// It could be that the client zone is not the owner or
	// the particular operation is not allowd in the context.
	//
	class NS_EPERM : public SystemException {
	public:
		NS_EPERM(uint_t minor, CompletionStatus completed);

		virtual			~NS_EPERM();

		static NS_EPERM	*_exnarrow(Exception *exceptp);
	};

	//
	// Environment passed with each invocation.
	// Stores system exceptions generated during the invocation.
	// Has storage for one system exception to avoid doing a new.
	//
	class Environment {
	public:
		Environment();

#ifdef _KERNEL_ORB
		//
		// This constructor is only for use by ORB internals.
		//
#if (SOL_VERSION >= __s10) && !defined(UNODE)
#ifdef _KERNEL
		Environment(ID_node &src_node,
		    zoneid_t zone = GLOBAL_ZONEID,
		    uint32_t cluster_id = PHYSICAL_CLUSTER_ID,
		    uint64_t zone_uniq_id = GLOBAL_ZONEUNIQID);
#else
		Environment(ID_node &src_node,
		    zoneid_t zone = GLOBAL_ZONEID,
		    uint32_t cluster_id = PHYSICAL_CLUSTER_ID,
		    uint64_t zone_uniq_id = 0);
#endif	// _KERNEL

#else	// SOL_VERSION >= __s10 && !defined(UNODE)
		Environment(ID_node &src_node);
#endif	// SOL_VERSION >= __s10 && !defined(UNODE)

#endif	// _KERNEL_ORB

		~Environment();

#ifdef _KERNEL_ORB
		//
		// This method is only for use by ORB internals.
		//
		ID_node		&get_src_node();

		//
		// This method indicates whether the invocation this
		// environment is a part of comes from a local client or not.
		//
		bool is_local_client();
#endif

		//
		// Debug-only aids used to show that environment has been used
		// for invocation or contains an exception and needs checking
		//
		void	mark_used();
		void	has_checked();
		void	check_used(char *s);

		//
		// Returns pointer to exception (either user or system)
		// NULL if none
		//
		Exception	*exception();

		//
		// Check if a system_exception exists
		//
		SystemException	*sys_exception();

		// To set any Exception
		void		exception(Exception *p);

		// To set system_exception without requiring to do a new
		void		system_exception(const SystemException &s);

		// To delete any old exception if any
		void		clear();

		// Disconnect exception from Environment object
		CORBA::Exception	*Environment::release_exception();

		//
		// XXX - information about blocking should eventually move
		// to the invocation_mode.
		//
		bool			is_nonblocking();
		void			set_nonblocking();
		void			clear_nonblocking();
		os::mem_alloc_type	nonblocking_type();

		//
		// To manage the service_freezing member below.
		//
		bool			service_is_freezing();
		void			set_freezing();
		void			clear_freezing();

		//
		// To manage the freeze_retry member below.
		//
		bool			get_freeze_retry();
		void			set_freeze_retry();
		void			clear_freeze_retry();

		//
		// Invocations on HA objects have a transaction context.
		// We keep a pointer to it.
		// The replication framework sets the pointer and does
		// any necessary casting.
		//
		void		*trans_ctxp;

#ifdef _KERNEL_ORB
		//
		// Test whether the current invocation came from a client
		// node that is dead. Invocations from dead nodes are called
		// orphan requests.
		//
		// This test does not know anything about nested invocations.
		//
		// This test is only useful for the server side.
		// While this test can be executed on the client side,
		// a client side test will never find an orphan.
		//
		bool	is_orphan();
#endif	// _KERNEL_ORB

#if (SOL_VERSION >= __s10) && !defined(UNODE)
		zoneid_t	get_zone_id() const;
		uint64_t	get_zone_uniqid() const;
		uint32_t	get_cluster_id() const;
		void		set_zone_id(zoneid_t zone);
		void		set_zone_uniqid(uint64_t zone_uniq_id);
		void		set_cluster_id(uint32_t cluster_id);
#endif	// (SOL_VERSION >= __s10) && !defined(UNODE)

	private:
		void done();

		// Disallow assignments
		Environment &operator = (const Environment &);

		// Disallow Copy constructor.
		Environment(const Environment &e);

#ifdef DEBUG
		//
		// we use needs_checking flag to make sure that callers check
		// and handle any exceptions resulting from a call
		//
		bool		needs_checking;
#endif
		bool		nonblocking;

		//
		// Set when an invocation on an HA service comes in
		// while the service is freezing.
		//
		bool		service_freezing;

		//
		// Used by hxdoors to indicate that an invocation that came to
		// the primary needs to be retried because the primary is
		// freezing.
		//
		bool		freeze_retry;

#ifdef _KERNEL_ORB
		// Identifies the source node for this invocation.
		ID_node		source_node;
#endif

		Exception	*_ptr;

#if (SOL_VERSION >= __s10) && !defined(UNODE)
		//
		// Zone information
		// We identify a running zone based on its zone_id,
		// but zone ids can be recycled. So, a zone named "foo" could
		// get a zone_id that is same as the zone_id it got in one
		// of its previous generations. We use zone_uniqid to
		// distinguish between such cases, as zone_uniqid is a unique
		// generation number for zones.
		//
		zoneid_t	zone_id;
		uint32_t	cluster_id;
		uint32_t	pad;
		uint64_t	zone_uniqid;
#endif

		//
		// Place to hold one system exception
		// Avoids need to do a new when generating a system exception
		//
		SystemException	sys_ex;

	};

	//
	// This class is used to create a proxy for the CORBA::Object
	// so the "builtin" methods can be called
	// (see usr/src/common/cl/interfaces/idl/corba.idl).
	//
	class Object_stub : public Object {
	public:
		// Expand inf_typeid inline to avoid nested include files.
		virtual inf_descriptor *_get_dynamic_descriptor(
		    const uint32_t tid[4], Environment &_environment);
		virtual void _generic_method(octet_seq_t &data,
		    object_seq_t &objs, Environment &_environment);

	protected:
		Object_stub() {}
		~Object_stub() {}
	};
};

// Convenience typedefs
typedef CORBA::Environment Environment;
typedef CORBA::ExceptionStatus ExceptionStatus;

//
// exception_major_data - will hold the constant data for an exceptions
// not generated by the IDL compiler.
//
class exception_major_data {
public:
	CORBA::TypeId	tid()	{ return (&id[0]); }

	CORBA::MD5_Tid	id;
	char		*name;
};

extern exception_major_data	major_translation[];

// Define the major numbers for the predefined errors
enum {
	UserException_major	= CORBA::user_exception,
	SystemException_major	= CORBA::system_exception,
	BAD_PARAM_major		= CORBA::bad_param,
	COMM_FAILURE_major	= CORBA::comm_failure,
	INV_OBJREF_major	= CORBA::inv_objref,
	WOULDBLOCK_major	= CORBA::wouldblock,
	RETRY_NEEDED_major	= CORBA::retry_needed,
	PRIMARY_FROZEN_major	= CORBA::primary_frozen,
	VERSION_Exception_major	= CORBA::version_exception,
	CTX_EACCESS_major	= CORBA::ctx_eaccess,
	NS_EPERM_major		= CORBA::ns_eperm
};

extern bool	_ox_equal_tid(CORBA::TypeId t1, CORBA::TypeId t2);
extern void	_ox_put_tid(service &, CORBA::TypeId);
extern void	_ox_get_tid(service &, CORBA::TypeId);

//
// Cast is an internal operation for receive functions.
// It assumes a non-nil object reference and a known type id.
//
extern void *_ox_cast(CORBA::Object_ptr, CORBA::TypeId);

#include <orb/invo/corba_in.h>

#endif	/* _CORBA_H */