require 'set' require 'aquarium/aspects/join_point' require 'aquarium/aspects/exclusion_handler' require 'aquarium/utils' require 'aquarium/extensions' require 'aquarium/finders/finder_result' require 'aquarium/finders/type_finder' require 'aquarium/finders/method_finder' require 'aquarium/aspects/default_objects_handler' module Aquarium module Aspects # == Pointcut # Pointcuts are queries on JoinPoints combined with binding of context data to # that will be useful during advice execution. The Pointcut locates the join points # that match the input criteria, remembering the found join points as well as the # the criteria that yielded no matches (mostly useful for debugging Pointcut definitions) class Pointcut include Aquarium::Utils::ArrayUtils include Aquarium::Utils::HashUtils include Aquarium::Utils::OptionsUtils include Aquarium::Utils::SetUtils include ExclusionHandler include DefaultObjectsHandler attr_reader :specification # Construct a Pointcut for methods in types or objects. # Pointcut.new :join_points => [...] | :type{s} => [...] | :object{s} => [...] \ # {, :method{s} => [], :method_options => [...], \ # :attribute{s} => [...], :attribute_options[...]} # where the "{}" indicate optional elements. Most of the arguments have many # synonyms, shown below, to promote an English-like DSL. # # :join_points => join_point || [join_point_list]:: # :join_point => join_point || [join_point_list]:: # :for_join_points => join_point || [join_point_list]:: # :for_join_point => join_point || [join_point_list]:: # :on_join_points => join_point || [join_point_list]:: # :on_join_point => join_point || [join_point_list]:: # :within_join_points => join_point || [join_point_list]:: # :within_join_point => join_point || [join_point_list]:: # One or an array of join_points. # # :types => type || [type_list]:: # :type => type || [type_list]:: # :for_types => type || [type_list]:: # :for_type => type || [type_list]:: # :on_types => type || [type_list]:: # :on_type => type || [type_list]:: # :within_types => type || [type_list]:: # :within_type => type || [type_list]:: # One or an array of types, type names and/or type regular expessions to match. # # :types_and_descendents => type || [type_list]:: # :type_and_descendents => type || [type_list]:: # :types_and_ancestors => type || [type_list]:: # :type_and_ancestors => type || [type_list]:: # :for_types_and_ancestors => type || [type_list]:: # :for_type_and_ancestors => type || [type_list]:: # :on_types_and_descendents => type || [type_list]:: # :on_type_and_descendents => type || [type_list]:: # :on_types_and_ancestors => type || [type_list]:: # :on_type_and_ancestors => type || [type_list]:: # :within_types_and_descendents => type || [type_list]:: # :within_type_and_descendents => type || [type_list]:: # :within_types_and_ancestors => type || [type_list]:: # :within_type_and_ancestors => type || [type_list]:: # One or an array of types and either their descendents or ancestors. # If you want both the descendents _and_ ancestors, use both options. # # :objects => object || [object_list]:: # :object => object || [object_list]:: # :for_objects => object || [object_list]:: # :for_object => object || [object_list]:: # :on_objects => object || [object_list]:: # :on_object => object || [object_list]:: # :within_objects => object || [object_list]:: # :within_object => object || [object_list]:: # Objects to match. # # :default_objects => object || [object_list]:: # :default_object => object || [object_list]:: # An "internal" flag used by AspectDSL#pointcut when no object or type is specified, # the value of :default_objects will be used, if defined. AspectDSL#pointcut sets the # value to self, so that the user doesn't have to in the appropriate contexts. # This flag is subject to change, so don't use it explicitly! # # :methods => method || [method_list]:: # :method => method || [method_list]:: # :within_methods => method || [method_list]:: # :within_method => method || [method_list]:: # :calling => method || [method_list]:: # :calls_to => method || [method_list]:: # :invoking => method || [method_list]:: # :invocations_of => method || [method_list]:: # :sending_message_to => method || [method_list]:: # One or an array of methods, method names and/or method regular expessions to match. # By default, unless :attributes are specified, searches for public instance methods # with the method option :exclude_ancestor_methods implied, unless explicit method # options are given. # # :method_options => [options]:: # One or more options supported by Aquarium::Finders::MethodFinder. The :exclude_ancestor_methods # option is most useful. # # :reading => attribute || [attribute_list]:: # :writing => attribute || [attribute_list]:: # :changing => attribute || [attribute_list]:: # :accessing => attribute || [attribute_list]:: # One or an array of attribute names and/or regular expessions to match. # This is syntactic sugar for the corresponding attribute readers and/or writers # methods. # If :reading is specified, just attribute readers are matched. # If :writing is specified, just attribute writers are matched. # If :accessing is specified, both readers and writers are matched. # Any matches will be joined with the matched :methods.. # # :attributes => attribute || [attribute_list]:: # :attribute => attribute || [attribute_list]:: # One or an array of attribute names and/or regular expessions to match. # This is syntactic sugar for the corresponding attribute readers and/or writers # methods, as specified using the :attrbute_options. Any matches will be # joined with the matched :methods.. # # :attribute_options => [options]:: # One or more of :readers, :reader (synonymous), # :writers, and/or :writer (synonymous). By default, both # readers and writers are matched. # :reading => ... is synonymous with :attributes => ..., # :attribute_options => [:readers]. # :writing => ... and :changing => ... are synonymous with :attributes => ..., # :attribute_options => [:writers]. # :accessing => ... is synonymous with :attributes => .... # # :exclude_pointcuts => pc || [pc_list]:: # :exclude_pointcut => pc || [pc_list]:: # :exclude_join_points => jp || [jp_list]:: # :exclude_join_point => jp || [jp_list]:: # :exclude_types => type || [type_list]:: # :exclude_types => type || [type_list]:: # :exclude_type => type || [type_list]:: # :exclude_objects => object || [object_list]:: # :exclude_object => object || [object_list]:: # :exclude_methods => method || [method_list]:: # :exclude_method => method || [method_list]:: # :exclude_attributes => attribute || [attribute_list]:: # :exclude_attribute => attribute || [attribute_list]:: # Also exclude_{synonyms} of the same options... # Exclude the specified "things" from the matched join points. If pointcuts are # excluded, they should be subsets of the matched pointcuts. Otherwise, the # resulting pointcut will be empty! # # :exclude_types_and_descendents => type || [type_list]:: # :exclude_type_and_descendents => type || [type_list]:: # :exclude_types_and_ancestors => type || [type_list]:: # :exclude_type_and_ancestors => type || [type_list]:: # Exclude the specified types and their descendents, ancestors. # If you want to exclude both the descendents _and_ ancestors, use both options. # # Pointcut.new also accepts all the "universal" options documented in OptionsUtils. def initialize options = {} init_specification options, CANONICAL_OPTIONS return if noop init_candidate_types init_candidate_objects init_candidate_join_points init_join_points end attr_reader :join_points_matched, :join_points_not_matched, :specification, :candidate_types, :candidate_types_excluded, :candidate_objects, :candidate_join_points # Two Considered equivalent only if the same join points matched and not_matched sets are equal, # the specifications are equal, and the candidate types and candidate objects are equal. # if you care only about the matched join points, then just compare #join_points_matched def eql? other object_id == other.object_id || (specification == other.specification && candidate_types == other.candidate_types && candidate_types_excluded == other.candidate_types_excluded && candidate_objects == other.candidate_objects && join_points_not_matched == other.join_points_not_matched && join_points_matched == other.join_points_matched) # not_matched is probably smaller, so do first. end alias :== :eql? def empty? return join_points_matched.empty? && join_points_not_matched.empty? end def inspect "Pointcut: {specification: #{specification.inspect}, candidate_types: #{candidate_types.inspect}, candidate_types_excluded: #{candidate_types_excluded.inspect}, candidate_objects: #{candidate_objects.inspect}, join_points_matched: #{join_points_matched.inspect}, join_points_not_matched: #{join_points_not_matched.inspect}}" end alias to_s inspect CANONICAL_OPTIONS = { "types" => %w[type for_type for_types on_type on_types in_type in_types within_type within_types], "objects" => %w[object for_object for_objects on_object on_objects in_object in_objects within_object within_objects], "join_points" => %w[join_point for_join_point for_join_points on_join_point on_join_points within_join_point within_join_points], "methods" => %w[method within_method within_methods calling invoking calls_to invocations_of sending_message_to sending_messages_to], "attributes" => %w[attribute accessing], "method_options" => %w[method_option restricting_methods_to], "attribute_options" => %w[attribute_option], "types_and_descendents" => %w[type_and_descendents on_type_and_descendents on_types_and_descendents within_type_and_descendents within_types_and_descendents], "types_and_ancestors" => %w[type_and_ancestors on_type_and_ancestors on_types_and_ancestors within_type_and_ancestors within_types_and_ancestors], "default_objects" => %w[default_object] } %w[types objects join_points methods types_and_descendents types_and_ancestors].each do |key| CANONICAL_OPTIONS["exclude_#{key}"] = CANONICAL_OPTIONS[key].map {|x| "exclude_#{x}"} end CANONICAL_OPTIONS["methods"].dup.each do |synonym| CANONICAL_OPTIONS["methods"] << "#{synonym}_methods_matching" end CANONICAL_OPTIONS["exclude_pointcuts"] = %w[exclude_pointcut exclude_on_pointcut exclude_on_pointcuts exclude_within_pointcut exclude_within_pointcuts] ATTRIBUTE_OPTIONS = %w[reading writing changing] ALL_ALLOWED_OPTIONS = ATTRIBUTE_OPTIONS + CANONICAL_OPTIONS.keys.inject([]) {|ary,i| ary << i << CANONICAL_OPTIONS[i]}.flatten ALL_ALLOWED_OPTION_SYMBOLS = ALL_ALLOWED_OPTIONS.map {|o| o.intern} def all_allowed_option_symbols ALL_ALLOWED_OPTION_SYMBOLS end CANONICAL_OPTIONS.keys.each do |name| module_eval(<<-EOF, __FILE__, __LINE__) def #{name}_given @specification[:#{name}] end def #{name}_given? not (#{name}_given.nil? or #{name}_given.empty?) end EOF end def self.make_attribute_reading_writing_options options_hash result = {} [:writing, :changing, :reading].each do |attr_key| unless options_hash[attr_key].nil? or options_hash[attr_key].empty? result[:attributes] ||= Set.new([]) result[:attribute_options] ||= Set.new([]) result[:attributes].merge(Aquarium::Utils::ArrayUtils.make_array(options_hash[attr_key])) attr_opt = attr_key == :reading ? :readers : :writers result[:attribute_options] << attr_opt end end result end protected attr_writer :join_points_matched, :join_points_not_matched, :specification, :candidate_types, :candidate_types_excluded, :candidate_objects, :candidate_join_points def init_type_specific_specification original_options, options_hash @specification.merge! Pointcut.make_attribute_reading_writing_options(options_hash) # Map the method options to their canonical values: @specification[:method_options] = Aquarium::Finders::MethodFinder.init_method_options(@specification[:method_options]) use_default_objects_if_defined unless (types_given? || objects_given?) raise Aquarium::Utils::InvalidOptions.new(":all is not yet supported for :attributes.") if @specification[:attributes] == Set.new([:all]) if options_hash[:reading] and (options_hash[:writing] or options_hash[:changing]) unless options_hash[:reading].eql?(options_hash[:writing]) or options_hash[:reading].eql?(options_hash[:changing]) raise Aquarium::Utils::InvalidOptions.new(":reading and :writing/:changing can only be used together if they refer to the same set of attributes.") end end init_methods_specification options_hash end def init_methods_specification options match_all_methods if ((no_methods_specified and no_attributes_specified) or all_methods_specified) end def match_all_methods @specification[:methods] = Set.new([:all]) end def no_methods_specified @specification[:methods].nil? or @specification[:methods].empty? end def all_methods_specified methods_spec = @specification[:methods].to_a methods_spec.include?(:all) or methods_spec.include?(:all_methods) end def no_attributes_specified @specification[:attributes].nil? or @specification[:attributes].empty? end private def init_candidate_types finder_options = {} exclude_finder_options = {} ['', 'exclude_'].each do |prefix| ['', '_and_ancestors', '_and_descendents'].each do |suffix| # Because the user might be asking for descendents and/or ancestors, we convert explicitly-specified # types into names, then "refind" them. While less efficient, it makes the code more uniform. eval <<-EOF #{prefix}type_regexps_or_names#{suffix} = @specification[:#{prefix}types#{suffix}].map do |t| Aquarium::Utils::TypeUtils.is_type?(t) ? t.name : t end unless #{prefix}type_regexps_or_names#{suffix}.nil? finder_options[:"#{prefix}types#{suffix}"] = #{prefix}type_regexps_or_names#{suffix} exclude_finder_options[:"types#{suffix}"] = #{prefix}type_regexps_or_names#{suffix} if "#{prefix}".length > 0 end EOF end end @candidate_types = Aquarium::Finders::TypeFinder.new.find finder_options @candidate_types_excluded = Aquarium::Finders::TypeFinder.new.find exclude_finder_options @specification[:exclude_types_calculated] = Set.new(@candidate_types_excluded.matched.keys) end def init_candidate_objects object_hash = {} (@specification[:objects].flatten - @specification[:exclude_objects].flatten).each do |o| object_hash[o] = Set.new([]) end @candidate_objects = Aquarium::Finders::FinderResult.new object_hash end def init_candidate_join_points @candidate_join_points = Aquarium::Finders::FinderResult.new @specification[:join_points].each do |jp| if jp.exists? @candidate_join_points.matched[jp] = Set.new([]) else @candidate_join_points.not_matched[jp] = Set.new([]) end end end def init_join_points @join_points_matched = Set.new @join_points_not_matched = Set.new find_join_points_for :type, (candidate_types - candidate_types_excluded), make_all_method_names find_join_points_for :object, candidate_objects, make_all_method_names add_join_points_for_candidate_join_points remove_excluded_join_points end def add_join_points_for_candidate_join_points @join_points_matched += @candidate_join_points.matched.keys @join_points_not_matched += @candidate_join_points.not_matched.keys end def remove_excluded_join_points @join_points_matched.delete_if do |jp| join_point_excluded? jp end end def find_join_points_for type_or_object_sym, candidates, method_names results = find_methods_for type_or_object_sym, candidates, method_names add_join_points results, type_or_object_sym end def find_methods_for type_or_object_sym, candidates, which_methods return Aquarium::Finders::FinderResult::NIL_OBJECT if candidates.matched.size == 0 Aquarium::Finders::MethodFinder.new.find type_or_object_sym => candidates.matched_keys, :methods => which_methods, :exclude_methods => @specification[:exclude_methods], :options => method_options end def add_join_points search_results, type_or_object_sym add_join_points_to @join_points_matched, search_results.matched, type_or_object_sym add_join_points_to @join_points_not_matched, search_results.not_matched, type_or_object_sym end def add_join_points_to which_join_points_list, results_hash, type_or_object_sym results_hash.each_pair do |type_or_object, method_name_list| method_name_list.each do |method_name| which_join_points_list << Aquarium::Aspects::JoinPoint.new( type_or_object_sym => type_or_object, :method_name => method_name, :instance_method => is_instance_methods?) end end end def is_instance_methods? not @specification[:method_options].include? :class end def make_all_method_names @specification[:methods] + make_attribute_method_names(@specification[:attributes], @specification[:attribute_options]) - @specification[:exclude_methods] end def make_attribute_method_names attribute_name_regexps_or_names, attribute_options = [] readers = make_attribute_readers attribute_name_regexps_or_names return readers if read_only attribute_options writers = make_attribute_writers readers return writers if write_only attribute_options return readers + writers end def make_attribute_readers attributes readers = attributes.map do |regexp_or_name| if regexp_or_name.kind_of? Regexp exp = remove_trailing_equals_and_or_dollar regexp_or_name.source Regexp.new(remove_leading_colon_or_at_sign(exp + '.*\b$')) else exp = remove_trailing_equals_and_or_dollar regexp_or_name.to_s remove_leading_colon_or_at_sign(exp.to_s) end end Set.new(readers.sort_by {|exp| exp.to_s}) end def make_attribute_writers attributes writers = attributes.map do |regexp_or_name| if regexp_or_name.kind_of? Regexp # remove the "\b$" from the end of the reader expression, if present. Regexp.new(remove_trailing_equals_and_or_dollar(regexp_or_name.source) + '=$') else regexp_or_name + '=' end end Set.new(writers.sort_by {|exp| exp.to_s}) end def read_only attribute_options read_option(attribute_options) && !write_option(attribute_options) end def write_only attribute_options write_option(attribute_options) && !read_option(attribute_options) end def read_option attribute_options attribute_options.include?(:readers) or attribute_options.include?(:reader) end def write_option attribute_options attribute_options.include?(:writers) or attribute_options.include?(:writer) end def method_options @specification[:method_options].to_a.map {|mo| mo == :all_methods ? :all : mo } end def remove_trailing_equals_and_or_dollar exp exp.gsub(/\=?\$?$/, '') end def remove_leading_colon_or_at_sign exp exp.gsub(/^\^?(@|:)/, '') end end end end