NAME
Rosetta::Utility::EasyBake - Perform common tasks with less effort
DEPENDENCIES
Perl Version: 5.008001
Core Modules: none
Non-Core Modules:
Rosetta 0.46COPYRIGHT AND LICENSE
This file is part of the Rosetta database portability library.
Rosetta is Copyright (c) 2002-2005, Darren R. Duncan. All rights reserved. Address comments, suggestions, and bug reports to perl@DarrenDuncan.net, or visit http://www.DarrenDuncan.net/ for more information.
Rosetta is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License (GPL) as published by the Free Software Foundation (http://www.fsf.org/); either version 2 of the License, or (at your option) any later version. You should have received a copy of the GPL as part of the Rosetta distribution, in the file named "GPL"; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
Linking Rosetta statically or dynamically with other modules is making a combined work based on Rosetta. Thus, the terms and conditions of the GPL cover the whole combination. As a special exception, the copyright holders of Rosetta give you permission to link Rosetta with independent modules, regardless of the license terms of these independent modules, and to copy and distribute the resulting combined work under terms of your choice, provided that every copy of the combined work is accompanied by a complete copy of the source code of Rosetta (the version of Rosetta used to produce the combined work), being distributed under the terms of the GPL plus this exception. An independent module is a module which is not derived from or based on Rosetta, and which is fully useable when not linked to Rosetta in any form.
Any versions of Rosetta that you modify and distribute must carry prominent notices stating that you changed the files and the date of any changes, in addition to preserving this original copyright notice and other credits. Rosetta is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
While it is by no means required, the copyright holders of Rosetta would appreciate being informed any time you create a modified version of Rosetta that you are willing to distribute, because that is a practical way of suggesting improvements to the standard version.
SYNOPSIS
This documentation section will be written later.
DESCRIPTION
The Rosetta::Utility::EasyBake Perl 5 module contains an optional set of convenience methods that let you define and perform common tasks using Rosetta while expending less effort in the process. You can have a significantly reduced application code size at the expense of some flexibility.
This module is implemented as a stateless utility class, and its methods are higher level wrappers around Rosetta and SQL::Routine methods. When one of its methods would conceptually be a 'Rosetta::Interface::*' method, it will take an object of that class as its first argument. The kind of functionality that EasyBake has an outward appearance relative to 'Rosetta' that resembles the general appearance of many DBIx wrappers relative to 'DBI'.
Rosetta::Utility::EasyBake contains some functionality that is common to Rosetta::Validator and Rosetta::Emulator::DBI, plus miscellaneous other modules and applications, so that each of those doesn't have to maintain its own copy.
While it is fairly new, you should consider this EasyBake module to be deprecated and you should not use it except for quick-and-dirty applications or experimental purposes. Writers of reuseable modules that want to use and/or extend Rosetta, particularly modules providing a database access or object persistence solution, should write directly to the 'Rosetta' module, which is a lot more flexible and will be better maintained. Likewise if you're making a large application having a distinct database access layer within it. Your own custom equivalent of what EasyBake does will serve you better in many cases.
SYNTAX
This class does not export any functions or methods, so you need to call them using object notation. This means using Class->function() for functions and $object->method() for methods. If you are inheriting this class for your own modules, then that often means something like $easybake->method().
CONSTRUCTOR FUNCTIONS
This function is stateless and can be invoked off of either this module's name or an existing module object, with the same result.
new()
my $easybake = Rosetta::Utility::EasyBake->new();
my $easybake2 = $easybake->new();This "getter" function will create and return a single Rosetta::Utility::EasyBake (or subclass) object.
CONFIGURATION INPUT VALIDATION METHODS
validate_connection_setup_options( SETUP_OPTIONS )
This function is used internally by build_connection() and build_child_connection() to confirm that its SETUP_OPTIONS argument is valid, prior to it changing the state of anything. This function is public so that external code can use it to perform advance validation on an identical configuration structure without side-effects. Note that this function is not thorough; except for the 'data_link_product'.'product_code' (Rosetta Engine class name), it does not test that Node attribute entries in SETUP_OPTIONS have defined values, and even that single attribute isn't tested beyond that it is defined. Testing for defined and mandatory option values is left to the SQL::Routine methods, which are only invoked by build_[child_]_connection().
DECLARATION BUILDERS FOR RAPID DEVELOPMENT
build_application()
my $app_intf = $easybake->build_application();This function is like Rosetta.new_application_interface() in that it will create and return a new Application Interface object. This function differs in that it will also create a new SQL::Routine model by itself and associate the new Interface with it, rather than requiring you to separately make the SRT model. The created model is as close to empty as possible; it contains only 2 SRT Nodes, which are 1 'application' and 1 related 'application_instance'; the latter becomes the SRT_NODE argument for new_application_interface(). The "id" and "si_name" of each new Node is given a default generated value. You can invoke get_app_inst_node() or get_srt_container() on the new Application Interface to access the SRT Nodes and model for further additions or changes.
build_application_with_node_trees( CHILDREN[, AUTO_ASSERT[, AUTO_IDS[, MATCH_SURR_IDS]]] )
my $app_intf = $easybake->build_application_with_node_trees( [...] );This function is like build_application() except that it lets you define the entire SRT Node hierarchy for the new model yourself; that definition is provided in the CHILDREN argument. This function expects you to define the 'application' and 'application_instance' Nodes yourself, in CHILDREN, and it will link the new Application Interface to the first 'application_instance' Node that it finds in the newly created SRT model. This method invokes SQL::Routine->build_container( CHILDREN, AUTO_ASSERT, AUTO_IDS, MATCH_SURR_IDS ) to do most of the work.
build_environment( ENGINE_NAME )
my $env_intf = $easybake->build_environment( 'Rosetta::Engine::Generic' );This function is like build_application() except that it will also create a new 'data_link_product' Node, using ENGINE_NAME as the 'product_code' attribute, and it will create a new associated Environment Interface object, that fronts a newly instantiated Engine object of the ENGINE_NAME class; the Environment Interface is returned.
build_child_environment( APP_INTF, ENGINE_NAME )
my $env_intf = $easybake->build_child_environment( $app_intf, 'Rosetta::Engine::Generic' );This function is like build_environment( ENGINE_NAME ) except that it will reuse the Application Interface given in APP_INTF, and associated Nodes, rather than making new ones. Moreover, if an Environment Interface with the same 'product_code' already exists under the current Application Interface, then build_child_environment() will not create or change anything, but simply return the existing Environment Interface object instead of a new one.
build_connection( SETUP_OPTIONS[, RT_SI_NAME[, RT_ID]] )
my $conn_intf_sqlite = $easybake->build_connection( {
'data_storage_product' => {
'product_code' => 'SQLite',
'is_file_based' => 1,
},
'data_link_product' => {
'product_code' => 'Rosetta::Engine::Generic',
},
'catalog_instance' => {
'file_path' => 'test',
},
} );
my $conn_intf_mysql = $easybake->build_connection( {
'data_storage_product' => {
'product_code' => 'MySQL',
'is_network_svc' => 1,
},
'data_link_product' => {
'product_code' => 'Rosetta::Engine::Generic',
},
'catalog_link_instance' => {
'local_dsn' => 'test',
'login_name' => 'jane',
'login_pass' => 'pwd',
},
}, 'declare_conn_to_mysql', 3 );This function will create and return a new Connection Interface object plus the prerequisite SQL::Routine model and Interface and Engine objects. The SETUP_OPTIONS argument is a two-dimensional hash, where each outer hash element corresponds to a Node type and each inner hash element corresponds to an attribute name and value for that Node type. There are 6 allowed Node types: data_storage_product, data_link_product, catalog_instance, catalog_link_instance, catalog_instance_opt, catalog_link_instance_opt; the first 4 have a specific set of actual scalar or enumerated attributes that may be set; with the latter 2, you can set any number of virtual attributes that you choose. The "setup options" say what Rosetta Engine to test and how to configure it to work in your customized environment. The actual attributes of the first 4 Node types should be recognized by all Engines and have the same meaning to them; you can set any or all of them (see the SQL::Routine documentation for the list) except for "id" and "si_name", which are given default generated values. The build_connection() function requires that, at the very least, you provide a 'data_link_product'.'product_code' SETUP_OPTIONS value, since that specifies the class name of the Rosetta Engine that implements the Connection. The virtual attributes of the last 2 Node types are specific to each Engine (see the Engine's documentation for a list), though an Engine may not define any at all. This function will generate 1 Node each of the first 4 Node types, and zero or more each of the last 2 Node types, all of which are cross-associated, plus the same Nodes that build_application() does, plus 1 each of: 'catalog', catalog_link, 'routine', plus several child Nodes of the 'routine'. The new 'routine' that this function creates is what declares the new Connection Interface, and becomes its SRT Node. Since you are likely to declare many routines subsequently in the same SRT model (but unlikely to declare more of any of the other aforementioned Node types), this function lets you provide explicit "si_name" and "id" attributes for the new 'routine' Node only, in the optional arguments RT_SI_NAME and RT_ID respectively.
build_child_connection( INTERFACE, SETUP_OPTIONS[, RT_SI_NAME[, RT_ID]] )
my $conn_intf_postgres = $easybake->build_child_connection( $app_intf, {
'data_storage_product' => {
'product_code' => 'PostgreSQL',
'is_network_svc' => 1,
},
'catalog_link_instance' => {
'local_dsn' => 'test',
'login_name' => 'jane',
'login_pass' => 'pwd',
},
} );This function is like build_connection( SETUP_OPTIONS, RT_SI_NAME, RT_ID ) except that it will reuse the Application and/or Environment Interface that it is given in INTERFACE, and associated Nodes, rather than making new ones. If invoked off of an Environment Interface, then any 'data_link_product' info that might be provided in SETUP_OPTIONS is ignored. If invoked off of an Application Interface, this method will try to reuse an existing child Environment Interface, that matches the given 'data_link_product'.'product_code', before making a new one, just as build_child_environment() does. This method will not attempt to reuse any other types of Nodes, so if that's what you want, you can't use this method to do it.
STANDARD ROUTINE WRAPPER BUILDERS FOR RAPID DEVELOPMENT
For each of these functions, optional RT_SI_NAME and RT_ID arguments are provided; you can give explicit "si_name" and "id" attributes to the new 'routine' Node, or such values will be generated.
sroutine_catalog_list( INTERFACE[, RT_SI_NAME[, RT_ID] ])
This method will build and return a prepared wrapper function for the CATALOG_LIST built-in SRT standard routine, which when executed, will return a Literal Interface whose payload is an array ref having zero or more newly generated 'catalog_link' SRT Nodes, each of which represents an auto-detected database catalog instance.
sroutine_catalog_open( CONN_INTF[, RT_SI_NAME[, RT_ID] ])
This method will build and return a prepared wrapper procedure for the CATALOG_OPEN built-in SRT standard routine, which when executed, will change the invoked on Connection from a closed state to an opened state, and will return a Success Interface. The prepared procedure will take 2 optional arguments at execute() time, which are 'login_name' and 'login_pass'; these values will be used if and only if a 'login_name' and 'login_pass' were not provided by the 'catalog_link' SRT Node that was used to make the invoked from Connection Interface.
sroutine_catalog_close( CONN_INTF[, RT_SI_NAME[, RT_ID] ])
This method will build and return a prepared wrapper procedure for the CATALOG_CLOSE built-in SRT standard routine, which when executed, will change the invoked on Connection from an opened state to a closed state, and will return a Success Interface.
BUGS
This module is currently in pre-alpha development status, meaning that some parts of it will be changed in the near future, perhaps in incompatible ways.
SEE ALSO
perl(1), Rosetta::Utility::EasyBake::L::en, Rosetta, SQL::Routine, Locale::KeyedText, Rosetta::Validator, Rosetta::Emulator::DBI.