Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Rose::DB::Object::MetaUser:ContributedePerl:Object::Metadata::Relationship(3)

NAME
       Rose::DB::Object::Metadata::Relationship	- Base class for table
       relationship metadata objects.

SYNOPSIS
	 package MyRelationshipType;

	 use Rose::DB::Object::Metadata::Relationship;
	 our @ISA = qw(Rose::DB::Object::Metadata::Relationship);
	 ...

DESCRIPTION
       This is the base	class for objects that store and manipulate database
       table relationship metadata.  Relationship metadata objects are
       responsible for creating	object methods that fetch and/or manipulate
       objects from related tables.  See the Rose::DB::Object::Metadata
       documentation for more information.

   MAKING METHODS
       A Rose::DB::Object::Metadata::Relationship-derived object is
       responsible for creating	object methods that manipulate objects in
       related tables.	Each relationship object can make zero or more methods
       for each	available relationship method type.  A relationship method
       type describes the purpose of a method.	The default list of
       relationship method types contains only one type:

       "get"
	   A method that returns one or	more objects from the related table.

       Methods are created by calling make_methods.  A list of method types
       can be passed to	the call to make_methods.  If absent, the list of
       method types is determined by the auto_method_types method.  A list of
       all possible method types is available through the
       available_method_types method.

       These methods make up the "public" interface to relationship method
       creation.  There	are, however, several "protected" methods which	are
       used internally to implement the	methods	described above.  (The word
       "protected" is used here	in a vaguely C++ sense,	meaning	"accessible to
       subclasses, but not to the public.")  Subclasses	will probably find it
       easier to override and/or call these protected methods in order to
       influence the behavior of the "public" method maker methods.

       A Rose::DB::Object::Metadata::Relationship object delegates method
       creation	to a  Rose::Object::MakeMethods-derived	class.	Each
       Rose::Object::MakeMethods-derived class has its own set of method
       types, each of which takes it own set of	arguments.

       Using this system, four pieces of information are needed	to create a
       method on behalf	of a Rose::DB::Object::Metadata::Relationship-derived
       object:

       o   The relationship method type	(e.g., "get")

       o   The method maker class (e.g.,
	   Rose::DB::Object::MakeMethods::Generic)

       o   The method maker method type	(e.g., object_by_key)

       o   The method maker arguments (e.g., "interface	=> 'get'")

       This information	can be organized conceptually into a "method map" that
       connects	a relationship method type to a	method maker class and,
       finally,	to one particular method type within that class, and its
       arguments.

       There is	no default method map for the
       Rose::DB::Object::Metadata::Relationship	base class, but	here is	the
       method map from Rose::DB::Object::Metadata::Relationship::OneToOne as
       an example:

       "get_set"
	   Rose::DB::Object::MakeMethods::Generic, scalar, "interface =>
	   'get_set', ..."

       "get"
	   Rose::DB::Object::MakeMethods::Generic, object_by_key, ...

       Each item in the	map is a relationship method type.  For	each
       relationship method type, the method maker class, the method maker
       method type, and	the "interesting" method maker arguments are listed,
       in that order.

       The "..." in the	method maker arguments is meant	to indicate that
       arguments have been omitted.  Arguments that are	common to all
       relationship method types are routinely omitted from the	method map for
       the sake	of brevity.  If	there are no "interesting" method maker
       arguments, then "..." may appear	by itself, as shown above.

       The purpose of documenting the method map is to answer the question,
       "What kind of method(s) will be created by this relationship object for
       a given method type?"  Given the	method map, it's possible to read the
       documentation for each method maker class to determine how methods of
       the specified type behave when passed the listed	arguments.

       To this end, each Rose::DB::Object::Metadata::Relationship-derived
       class in	the Rose::DB::Object module distribution will list its method
       map in its documentation.  This is a concise way	to document the
       behavior	that is	specific to each relationship class, while omitting
       the common functionality	(which is documented here, in the relationship
       base class).

       Remember, the existence and behavior of the method map is really
       implementation detail.  A relationship object is	free to	implement the
       public method-making interface however it wants,	without	regard to any
       conceptual or actual method map.	 It must then, of course, document
       what kinds of methods it	makes for each of its method types, but	it
       does not	have to	use a method map to do so.

CLASS METHODS
       default_auto_method_types [TYPES]
	   Get or set the default list of auto_method_types.  TYPES should be
	   a list of relationship method types.	 Returns the list of default
	   relationship	method types (in list context) or a reference to an
	   array of the	default	relationship method types (in scalar context).
	   The default list is empty.

CONSTRUCTOR
       new PARAMS
	   Constructs a	new object based on PARAMS, where PARAMS are
	   name/value pairs.  Any object method	is a valid parameter name.

OBJECT METHODS
       available_method_types
	   Returns the full list of relationship method	types supported	by
	   this	class.

       auto_method_types [TYPES]
	   Get or set the list of relationship method types that are
	   automatically created when make_methods is called without an
	   explicit list of relationship method	types.	The default list is
	   determined by the default_auto_method_types class method.

       build_method_name_for_type TYPE
	   Return a method name	for the	relationship method type TYPE.
	   Subclasses must override this method.  The default implementation
	   causes a fatal error	if called.

       class [CLASS]
	   Get or set the name of the Rose::DB::Object-derived class that
	   fronts the foreign table referenced by this relationship.

       is_singular
	   Returns true	of the relationship may	refer to more than one related
	   object, false otherwise.  For example, this method returns true for
	   "is_singular" in
	   Rose::DB::Object::Metadata::Relationship::OneToMany objects,	but
	   false for "is_singular" in
	   Rose::DB::Object::Metadata::Relationship::ManyToOne objects.

	   Relationship	subclasses must	override this method and return	an
	   appropriate value.

       make_methods PARAMS
	   Create object method	used to	manipulate objects in related tables.
	   Any applicable column triggers are also added.  PARAMS are
	   name/value pairs.  Valid PARAMS are:

	   "preserve_existing BOOL"
	       Boolean flag that indicates whether or not to preserve existing
	       methods in the case of a	name conflict.

	   "replace_existing BOOL"
	       Boolean flag that indicates whether or not to replace existing
	       methods in the case of a	name conflict.

	   "target_class CLASS"
	       The class in which to make the method(s).  If omitted, it
	       defaults	to the calling class.

	   "types ARRAYREF"
	       A reference to an array of relationship method types to be
	       created.	 If omitted, it	defaults to the	list of	relationship
	       method types returned by	auto_method_types.

	   If any of the methods could not be created for any reason, a	fatal
	   error will occur.

       methods MAP
	   Set the list	of auto_method_types and method	names all at once.
	   MAP should be a reference to	a hash whose keys are method types and
	   whose values	are either undef or method names.  If a	value is
	   undef, then the method name for that	method type will be generated
	   by calling build_method_name_for_type, as usual.  Otherwise,	the
	   specified method name will be used.

       method_types [TYPES]
	   This	method is an alias for the auto_method_types method.

       method_name TYPE	[, NAME]
	   Get or set the name of the relationship method of type TYPE.

       name [NAME]
	   Get or set the name of the relationship.  This name must be unique
	   among all other relationships for a given Rose::DB::Object-derived
	   class.

       type
	   Returns a string describing the type	of relationship.  Subclasses
	   must	override this method.  The default implementation causes a
	   fatal error if called.

PROTECTED API
       These methods are not part of the public	interface, but are supported
       for use by subclasses.  Put another way,	given an unknown object	that
       "isa" Rose::DB::Object::Metadata::Relationship, there should be no
       expectation that	the following methods exist.  But subclasses, which
       know the	exact class from which they inherit, are free to use these
       methods in order	to implement the public	API described above.

       method_maker_arguments TYPE
	   Returns a hash (in list context) or reference to a hash (in scalar
	   context) of name/value arguments that will be passed	to the
	   method_maker_class when making the relationship method type TYPE.

       method_maker_class TYPE [, CLASS]
	   If CLASS is passed, the name	of the
	   Rose::Object::MakeMethods-derived class used	to create the object
	   method of type TYPE is set to CLASS.

	   Returns the name of the Rose::Object::MakeMethods-derived class
	   used	to create the object method of type TYPE.

       method_maker_type TYPE [, NAME]
	   If NAME is passed, the name of the method maker method type for the
	   relationship	method type TYPE is set	to NAME.

	   Returns the method maker method type	for the	relationship method
	   type	TYPE.

AUTHOR
       John C. Siracusa	(siracusa@gmail.com)

LICENSE
       Copyright (c) 2010 by John C. Siracusa.	All rights reserved.  This
       program is free software; you can redistribute it and/or	modify it
       under the same terms as Perl itself.

perl v5.24.1			  2Rose::DB::Object::Metadata::Relationship(3)

NAME | SYNOPSIS | DESCRIPTION | CLASS METHODS | CONSTRUCTOR | OBJECT METHODS | PROTECTED API | AUTHOR | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Rose::DB::Object::Metadata::Relationship&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help