// =-=-=-=-=-=-=-
    // passthru_file_rebalance - code which would notify the subtree of a change
    irods::error passthru_file_notify(
        irods::resource_plugin_context& _ctx,
        const std::string*               _opr ) {
        // =-=-=-=-=-=-=-
        // forward request for notify to children
        irods::error result = SUCCESS();
        irods::resource_child_map::iterator itr = _ctx.child_map().begin();
        for ( ; itr != _ctx.child_map().end(); ++itr ) {
            irods::error ret = itr->second.second->call(
                                   _ctx.comm(),
                                   irods::RESOURCE_OP_NOTIFY,
                                   _ctx.fco(),
                                   _opr );
            if ( !ret.ok() ) {
                irods::log( PASS( ret ) );
                result = ret;
            }
        }

        return result;

    } // passthru_file_notify

    // =-=-=-=-=-=-=-
    // random_file_rebalance - code which would rebalance the subtree
    irods::error random_file_rebalance(
        irods::resource_plugin_context& _ctx ) {
        // =-=-=-=-=-=-=-
        // forward request for rebalance to children
        irods::error result = SUCCESS();
        irods::resource_child_map::iterator itr = _ctx.child_map().begin();
        for ( ; itr != _ctx.child_map().end(); ++itr ) {
            irods::error ret = itr->second.second->call( _ctx.comm(), irods::RESOURCE_OP_REBALANCE, _ctx.fco() );
            if ( !( result = ASSERT_PASS( ret, "Failed calling child operation." ) ).ok() ) {
                irods::log( PASS( result ) );
            }
        }

        if ( !result.ok() ) {
            return PASS( result );
        }

        return update_resource_object_count(
                   _ctx.comm(),
                   _ctx.prop_map() );

    } // random_file_rebalancec

    // =-=-=-=-=-=-=-
    // interface for POSIX closedir
    irods::error pass_thru_file_closedir_plugin(
        irods::resource_plugin_context& _ctx ) {
        irods::error result = SUCCESS();
        irods::error ret;

        ret = pass_thru_check_params( _ctx );
        if ( !ret.ok() ) {
            result = PASSMSG( "pass_thru_file_closedir_plugin - bad params.", ret );
        }
        else {
            irods::resource_ptr resc;
            ret = pass_thru_get_first_chid_resc( _ctx.child_map(), resc );
            if ( !ret.ok() ) {
                result = PASSMSG( "pass_thru_file_closedir_plugin - failed getting the first child resource pointer.", ret );
            }
            else {
                ret = resc->call( _ctx.comm(), irods::RESOURCE_OP_CLOSEDIR, _ctx.fco() );
                result = PASSMSG( "pass_thru_file_closedir_plugin - failed calling child closedir.", ret );
            }
        }
        return result;
    } // pass_thru_file_closedir_plugin

    // =-=-=-=-=-=-=-
    // interface for POSIX Open
    irods::error round_robin_file_notify(
        irods::resource_plugin_context& _ctx,
        const std::string*               _opr ) {
        // =-=-=-=-=-=-=-
        // get the child resc to call
        irods::resource_ptr resc;
        irods::error err = round_robin_get_resc_for_call< irods::file_object >( _ctx, resc );
        if ( !err.ok() ) {
            std::stringstream msg;
            msg << "failed.";
            return PASSMSG( msg.str(), err );
        }

        // =-=-=-=-=-=-=-
        // call open operation on the child
        return resc->call< const std::string* >(
                   _ctx.comm(),
                   irods::RESOURCE_OP_NOTIFY,
                   _ctx.fco(),
                   _opr );

    } // round_robin_file_open

    // =-=-=-=-=-=-=-
    // interface for POSIX readdir
    irods::error passthru_file_readdir_plugin(
        irods::resource_plugin_context& _ctx,
        struct rodsDirent**                 _dirent_ptr ) {
        irods::error result = SUCCESS();
        irods::error ret;

        ret = passthru_check_params( _ctx );
        if ( !ret.ok() ) {
            result = PASSMSG( "passthru_file_readdir_plugin - bad params.", ret );
        }
        else {
            irods::resource_ptr resc;
            ret = passthru_get_first_child_resc( _ctx.child_map(), resc );
            if ( !ret.ok() ) {
                result = PASSMSG( "passthru_file_readdir_plugin - failed getting the first child resource pointer.", ret );
            }
            else {
                ret = resc->call<struct rodsDirent**>( _ctx.comm(), irods::RESOURCE_OP_READDIR, _ctx.fco(), _dirent_ptr );
                result = PASSMSG( "passthru_file_readdir_plugin - failed calling child readdir.", ret );
            }
        }
        return result;
    } // passthru_file_readdir_plugin

    /// =-=-=-=-=-=-=-
    /// @brief interface to notify of a file unregistration
    irods::error pass_thru_file_unregistered(
        irods::resource_plugin_context& _ctx ) {
        irods::error result = SUCCESS();
        irods::error ret;

        ret = pass_thru_check_params( _ctx );
        if ( !ret.ok() ) {
            result = PASSMSG( "bad params.", ret );
        }
        else {
            irods::resource_ptr resc;
            ret = pass_thru_get_first_chid_resc( _ctx.child_map(), resc );
            if ( !ret.ok() ) {
                result = PASSMSG( "failed getting the first child resource pointer.", ret );
            }
            else {
                ret = resc->call( _ctx.comm(), irods::RESOURCE_OP_UNREGISTERED, _ctx.fco() );

                result = PASSMSG( "failed calling child unregistered.", ret );
            }
        }
        return result;
    } // pass_thru_file_unregistered

    // =-=-=-=-=-=-=-
    // interface for POSIX Stat
    irods::error pass_thru_file_stat_plugin(
        irods::resource_plugin_context& _ctx,
        struct stat*                        _statbuf ) {
        irods::error result = SUCCESS();
        irods::error ret;

        ret = pass_thru_check_params( _ctx );
        if ( !ret.ok() ) {
            result = PASSMSG( "pass_thru_file_stat_plugin - bad params.", ret );
        }
        else {
            irods::resource_ptr resc;
            ret = pass_thru_get_first_chid_resc( _ctx.child_map(), resc );
            if ( !ret.ok() ) {
                result = PASSMSG( "pass_thru_file_stat_plugin - failed getting the first child resource pointer.", ret );
            }
            else {
                ret = resc->call<struct stat*>( _ctx.comm(), irods::RESOURCE_OP_STAT, _ctx.fco(), _statbuf );
                result = PASSMSG( "pass_thru_file_stat_plugin - failed calling child stat.", ret );
            }
        }
        return result;
    } // pass_thru_file_stat_plugin

    // =-=-=-=-=-=-=-
    /// @brief Check the general parameters passed in to most plugin functions
    irods::error pass_thru_check_params(
        irods::resource_plugin_context& _ctx ) {
        // =-=-=-=-=-=-=-
        // verify that the resc context is valid
        irods::error ret = _ctx.valid();
        if ( !ret.ok() ) {
            std::stringstream msg;
            msg << " - resource context is invalid.";
            return PASSMSG( msg.str(), ret );
        }

        return SUCCESS();

    } // pass_thru_check_params

    // =-=-=-=-=-=-=-
    // passthruStageToCache - This routine is for testing the TEST_STAGE_FILE_TYPE.
    // Just copy the file from filename to cacheFilename. optionalInfo info
    // is not used.
    irods::error pass_thru_stage_to_cache_plugin(
        irods::resource_plugin_context& _ctx,
        const char*                         _cache_file_name ) {
        irods::error result = SUCCESS();
        irods::error ret;

        ret = pass_thru_check_params( _ctx );
        if ( !ret.ok() ) {
            result = PASSMSG( "pass_thru_stage_to_cache_plugin - bad params.", ret );
        }
        else {
            irods::resource_ptr resc;
            ret = pass_thru_get_first_chid_resc( _ctx.child_map(), resc );
            if ( !ret.ok() ) {
                result = PASSMSG( "pass_thru_stage_to_cache_plugin - failed getting the first child resource pointer.", ret );
            }
            else {
                ret = resc->call<const char*>( _ctx.comm(), irods::RESOURCE_OP_STAGETOCACHE, _ctx.fco(), _cache_file_name );
                result = PASSMSG( "pass_thru_stage_to_cache_plugin - failed calling child stagetocache.", ret );
            }
        }
        return result;
    } // pass_thru_stage_to_cache_plugin

    // =-=-=-=-=-=-=-
    // unixSyncToArch - This routine is for testing the TEST_STAGE_FILE_TYPE.
    // Just copy the file from cacheFilename to filename. optionalInfo info
    // is not used.
    irods::error mock_archive_synctoarch_plugin(
        irods::resource_plugin_context& _ctx,
        char*                           _cache_file_name ) {
        irods::error result = SUCCESS();

        // =-=-=-=-=-=-=-
        // Check the operation parameters and update the physical path
        irods::error ret = unix_check_params_and_path< irods::file_object >( _ctx );
        if ( ( result = ASSERT_PASS( ret, "Invalid plugin context." ) ).ok() ) {
            // =-=-=-=-=-=-=-
            // get ref to fco
            irods::file_object_ptr fco = boost::dynamic_pointer_cast< irods::file_object >( _ctx.fco() );

            // =-=-=-=-=-=-=-
            // get the vault path for the resource
            std::string path;
            ret = make_hashed_path(
                      _ctx.prop_map(),
                      fco->physical_path(),
                      path );
            if ( ( result = ASSERT_PASS( ret, "Failed to gen hashed path" ) ).ok() ) {
                // =-=-=-=-=-=-=-
                // append the hash to the path as the new 'cache file name'
                rodsLog( LOG_NOTICE, "mock archive :: cache file name [%s]", _cache_file_name );

                rodsLog( LOG_NOTICE, "mock archive :: new hashed file name for [%s] is [%s]",
                         fco->physical_path().c_str(), path.c_str() );

                // =-=-=-=-=-=-=-
                // make the directories in the path to the new file
                std::string new_path = path;
                std::size_t last_slash = new_path.find_last_of( '/' );
                new_path.erase( last_slash );
                ret = mock_archive_mkdir_r( new_path.c_str(), 0750 );
                if ( ( result = ASSERT_PASS( ret, "Mkdir error for \"%s\".", new_path.c_str() ) ).ok() ) {

                }
                // =-=-=-=-=-=-=-
                // make the copy to the 'archive'
                int status = mockArchiveCopyPlugin( fco->mode(), _cache_file_name, path.c_str() );
                if ( ( result = ASSERT_ERROR( status >= 0, status, "Sync to arch failed." ) ).ok() ) {
                    fco->physical_path( path );
                }
            }
        }

        return result;

    } // mock_archive_synctoarch_plugin

    // =-=-=-=-=-=-=-
    // interface for POSIX Write
    irods::error pass_thru_file_write_plugin(
        irods::resource_plugin_context& _ctx,
        void*                               _buf,
        int                                 _len ) {
        irods::error result = SUCCESS();
        irods::error ret;

        ret = pass_thru_check_params( _ctx );
        if ( !ret.ok() ) {
            result = PASSMSG( "bad params.", ret );
        }
        else {
            irods::resource_ptr resc;
            ret = pass_thru_get_first_chid_resc( _ctx.child_map(), resc );
            if ( !ret.ok() ) {
                result = PASSMSG( "failed getting the first child resource pointer.", ret );
            }
            else {
                ret = resc->call<void*, int>( _ctx.comm(), irods::RESOURCE_OP_WRITE, _ctx.fco(), _buf, _len );
                result = PASSMSG( "pass_thru_file_write_plugin - failed calling child write.", ret );
            }
        }
        return result;
    } // pass_thru_file_write_plugin

    // =-=-=-=-=-=-=-
    // interface for POSIX lseek
    irods::error pass_thru_file_lseek_plugin(
        irods::resource_plugin_context& _ctx,
        long long                        _offset,
        int                              _whence ) {
        irods::error result = SUCCESS();
        irods::error ret;

        ret = pass_thru_check_params( _ctx );
        if ( !ret.ok() ) {
            result = PASSMSG( "pass_thru_file_lseek_plugin - bad params.", ret );
        }
        else {
            irods::resource_ptr resc;
            ret = pass_thru_get_first_chid_resc( _ctx.child_map(), resc );
            if ( !ret.ok() ) {
                result = PASSMSG( "pass_thru_file_lseek_plugin - failed getting the first child resource pointer.", ret );
            }
            else {
                ret = resc->call<long long, int>( _ctx.comm(), irods::RESOURCE_OP_LSEEK, _ctx.fco(), _offset, _whence );
                result = PASSMSG( "pass_thru_file_lseek_plugin - failed calling child lseek.", ret );
            }
        }
        return result;
    } // pass_thru_file_lseek_plugin

    /// =-=-=-=-=-=-=-
    /// @brief interface for POSIX Unlink
    irods::error univ_mss_file_unlink(
        irods::resource_plugin_context& _ctx ) {
        // =-=-=-=-=-=-=-
        // check context
        irods::error err = univ_mss_check_param< irods::data_object >( _ctx );
        if ( !err.ok() ) {
            std::stringstream msg;
            msg << __FUNCTION__;
            msg << " - invalid context";
            return PASSMSG( msg.str(), err );

        }

        // =-=-=-=-=-=-=-
        // get the script property
        std::string script;
        err = _ctx.prop_map().get< std::string >( SCRIPT_PROP, script );
        if ( !err.ok() ) {
            return PASSMSG( __FUNCTION__, err );
        }

        // =-=-=-=-=-=-=-
        // snag a ref to the fco
        irods::data_object_ptr fco = boost::dynamic_pointer_cast< irods::data_object >( _ctx.fco() );
        std::string filename = fco->physical_path();

        execCmd_t execCmdInp;
        memset( &execCmdInp, 0, sizeof( execCmdInp ) );
        snprintf( execCmdInp.cmd, sizeof( execCmdInp.cmd ), "%s", script.c_str() );
        snprintf( execCmdInp.cmdArgv, sizeof( execCmdInp.cmdArgv ), "rm '%s'", filename.c_str() );
        snprintf( execCmdInp.execAddr, sizeof( execCmdInp.execAddr ), "localhost" );

        execCmdOut_t *execCmdOut = NULL;
        int status = _rsExecCmd( &execCmdInp, &execCmdOut );
        freeCmdExecOut( execCmdOut );

        if ( status < 0 ) {
            status = UNIV_MSS_UNLINK_ERR - errno;
            std::stringstream msg;
            msg << "univ_mss_file_unlink - failed for [";
            msg << filename;
            msg << "]";
            return ERROR( status, msg.str() );
        }

        return CODE( status );

    } // univ_mss_file_unlink

    /// =-=-=-=-=-=-=-
    /// @brief This routine copys data from the archive resource to the cache resource
    ///        in a compound resource composition
    irods::error load_balanced_file_stage_to_cache(
        irods::resource_plugin_context& _ctx,
        const char*                         _cache_file_name ) {
        irods::error result = SUCCESS();

        // =-=-=-=-=-=-=-
        // get the child resc to call
        irods::resource_ptr resc;
        irods::error err = load_balanced_get_resc_for_call< irods::file_object >( _ctx, resc );
        if ( ( result = ASSERT_PASS( err, "Failed to select load_balanced resource." ) ).ok() ) {
            // =-=-=-=-=-=-=-
            // call stage on the child
            err = resc->call< const char* >( _ctx.comm(), irods::RESOURCE_OP_STAGETOCACHE, _ctx.fco(), _cache_file_name );
            result = ASSERT_PASS( err, "Failed calling child operation." );
        }

        return result;
    } // load_balanced_file_stage_to_cache

    /// =-=-=-=-=-=-=-
    /// @brief interface for POSIX readdir
    irods::error round_robin_file_readdir(
        irods::resource_plugin_context& _ctx,
        struct rodsDirent**                 _dirent_ptr ) {
        // =-=-=-=-=-=-=-
        // get the child resc to call
        irods::resource_ptr resc;
        irods::error err = round_robin_get_resc_for_call< irods::collection_object >( _ctx, resc );
        if ( !err.ok() ) {
            std::stringstream msg;
            msg <<  __FUNCTION__;
            msg << " - failed.";
            return PASSMSG( msg.str(), err );
        }

        // =-=-=-=-=-=-=-
        // call readdir on the child
        return resc->call< struct rodsDirent** >( _ctx.comm(), irods::RESOURCE_OP_READDIR, _ctx.fco(), _dirent_ptr );

    } // round_robin_file_readdir

    /// =-=-=-=-=-=-=-
    /// @brief This routine is for testing the TEST_STAGE_FILE_TYPE.
    ///        Just copy the file from cacheFilename to filename. optionalInfo info
    ///        is not used.
    irods::error random_file_sync_to_arch(
        irods::resource_plugin_context& _ctx,
        const char*                         _cache_file_name ) {
        irods::error result = SUCCESS();

        // =-=-=-=-=-=-=-
        // get the child resc to call
        irods::resource_ptr resc;
        irods::error err = random_get_resc_for_call< irods::file_object >( _ctx, resc );
        if ( ( result = ASSERT_PASS( err, "Failed selecting random resource." ) ).ok() ) {

            // =-=-=-=-=-=-=-
            // call synctoarch on the child
            err = resc->call< const char* >( _ctx.comm(), irods::RESOURCE_OP_SYNCTOARCH, _ctx.fco(), _cache_file_name );
            result = ASSERT_PASS( err, "Failed calling child operation." );
        }

        return result;
    } // random_file_sync_to_arch

    /// =-=-=-=-=-=-=-
    /// @brief interface for POSIX readdir
    irods::error random_file_readdir(
        irods::resource_plugin_context& _ctx,
        struct rodsDirent**              _dirent_ptr ) {
        irods::error result = SUCCESS();

        // =-=-=-=-=-=-=-
        // get the child resc to call
        irods::resource_ptr resc;
        irods::error err = random_get_resc_for_call< irods::collection_object >( _ctx, resc );
        if ( ( result = ASSERT_PASS( err, "Failed to select random resource." ) ).ok() ) {

            // =-=-=-=-=-=-=-
            // call readdir on the child
            err = resc->call< struct rodsDirent** >( _ctx.comm(), irods::RESOURCE_OP_READDIR, _ctx.fco(), _dirent_ptr );
            result = ASSERT_PASS( err, "Failed calling child operation." );
        }

        return result;
    } // random_file_readdir

    /// =-=-=-=-=-=-=-
    /// @brief This routine is for testing the TEST_STAGE_FILE_TYPE.
    ///        Just copy the file from cacheFilename to filename. optionalInfo info
    ///        is not used.
    irods::error round_robin_file_sync_to_arch(
        irods::resource_plugin_context& _ctx,
        const char*                         _cache_file_name ) {
        // =-=-=-=-=-=-=-
        // get the child resc to call
        irods::resource_ptr resc;
        irods::error err = round_robin_get_resc_for_call< irods::file_object >( _ctx, resc );
        if ( !err.ok() ) {
            std::stringstream msg;
            msg <<  __FUNCTION__;
            msg << " - failed.";
            return PASSMSG( msg.str(), err );
        }

        // =-=-=-=-=-=-=-
        // call synctoarch on the child
        return resc->call< const char* >( _ctx.comm(), irods::RESOURCE_OP_SYNCTOARCH, _ctx.fco(), _cache_file_name );

    } // round_robin_file_sync_to_arch

    /// =-=-=-=-=-=-=-
    /// @brief interface for POSIX lseek
    irods::error random_file_lseek(
        irods::resource_plugin_context& _ctx,
        long long                        _offset,
        int                              _whence ) {
        irods::error result = SUCCESS();

        // =-=-=-=-=-=-=-
        // get the child resc to call
        irods::resource_ptr resc;
        irods::error err = random_get_resc_for_call< irods::file_object >( _ctx, resc );
        if ( ( result = ASSERT_PASS( err, "Failed to select random child." ) ).ok() ) {

            // =-=-=-=-=-=-=-
            // call lseek on the child
            err = resc->call< long long, int >( _ctx.comm(), irods::RESOURCE_OP_LSEEK, _ctx.fco(), _offset, _whence );
            result = ASSERT_PASS( err, "Failed calling child operation." );
        }

        return result;
    } // random_file_lseek

    // =-=-=-=-=-=-=-
    // interface for POSIX Unlink
    irods::error mock_archive_unlink_plugin(
        irods::resource_plugin_context& _ctx ) {
        irods::error result = SUCCESS();
        // =-=-=-=-=-=-=-
        // Check the operation parameters and update the physical path
        irods::error ret = unix_check_params_and_path< irods::file_object >( _ctx );
        if ( ( result = ASSERT_PASS( ret, "Invalid plugin context." ) ).ok() ) {

            // =-=-=-=-=-=-=-
            // get ref to fco
            irods::file_object_ptr fco = boost::dynamic_pointer_cast< irods::file_object >( _ctx.fco() );

            // =-=-=-=-=-=-=-
            // make the call to unlink
            int status = unlink( fco->physical_path().c_str() );

            // =-=-=-=-=-=-=-
            // error handling
            int err_status = UNIX_FILE_UNLINK_ERR - errno;
            result = ASSERT_ERROR( status >= 0, err_status, "Unlink error for: \"%s\", errno = \"%s\", status = %d.",
                                   fco->physical_path().c_str(), strerror( errno ), err_status );
        }

        return result;

    } // mock_archive_unlink_plugin