Class: Buildr::Artifact

Inherits:
Rake::FileTask show all
Includes:
Buildr, ActsAsArtifact
Defined in:
lib/buildr/packaging/artifact.rb

Overview

A file task referencing an artifact in the local repository.

This task includes all the artifact attributes (group, id, version, etc). It points to the artifact’s path in the local repository. When invoked, it will download the artifact into the local repository if the artifact does not already exist.

Note: You can enhance this task to create the artifact yourself, e.g. download it from a site that doesn’t have a remote repository structure, copy it from a different disk, etc.

Direct Known Subclasses

OptionalArtifact

Constant Summary collapse

DEFAULT_TYPE =

The default artifact type.

:jar

Constants included from ActsAsArtifact

Buildr::ActsAsArtifact::ARTIFACT_ATTRIBUTES, Buildr::ActsAsArtifact::MAVEN_METADATA

Constants included from Buildr

VERSION

Constants included from Ant

Buildr::Ant::VERSION

Instance Attribute Summary

Attributes included from ActsAsArtifact

#buildr_project, #classifier, #group, #id, #type, #version

Class Method Summary collapse

Instance Method Summary collapse

Methods included from ActsAsArtifact

#annotations_artifact, #final_version, #install, #javadoc_artifact, #maven_metadata_xml, #pom, #pom_xml, #snapshot?, #sources_artifact, #to_spec, #to_spec_hash, #uninstall, #upload, #upload_task

Methods included from Buildr

application, application=, #artifact, #artifact_ns, #artifacts, #concat, #define, ensure_rspec, environment, #filter, #group, #help, help, #install, #integration, options, #options, #project, #projects, #read, #repositories, rspec_present?, settings, #struct, #transitive, #unzip, #upload, #write, #zip

Methods included from Ant

#ant, dependencies, version

Methods inherited from Rake::FileTask

#contain?, #empty?, #exist?

Constructor Details

#initialize(*args) ⇒ Artifact

:nodoc:



406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
 
# File 'lib/buildr/packaging/artifact.rb', line 406

def initialize(*args) #:nodoc:
  super
  enhance do |task|
    # Default behavior: download the artifact from one of the remote repositories
    # if the file does not exist. But this default behavior is counter productive
    # if the artifact knows how to build itself (e.g. download from a different location),
    # so don't perform it if the task found a different way to create the artifact.
    task.enhance do
      if download_needed? task
        info "Downloading #{to_spec}"
        download
        pom.invoke rescue nil if pom && pom != self && classifier.nil?
      end
    end
  end
end

Class Method Details

.hash_to_file_name(hash) ⇒ Object

:call-seq:

hash_to_file_name(spec_hash) => file_name

Convert a hash spec to a file name.



398
399
400
401
402
 
# File 'lib/buildr/packaging/artifact.rb', line 398

def hash_to_file_name(hash)
  version = "-#{hash[:version]}" if hash[:version]
  classifier = "-#{hash[:classifier]}" if hash[:classifier]
  "#{hash[:id]}#{version}#{classifier}.#{extract_type(hash[:type]) || DEFAULT_TYPE}"
end

.list ⇒ Object

:call-seq:

list => specs

Returns an array of specs for all the registered artifacts. (Anything created from artifact, or package).



329
330
331
332
 
# File 'lib/buildr/packaging/artifact.rb', line 329

def list
  @artifacts ||= {}
  @artifacts.keys
end

.lookup(spec) ⇒ Object

:call-seq:

lookup(spec) => Artifact

Lookup a previously registered artifact task based on its specification (String or Hash).



320
321
322
323
 
# File 'lib/buildr/packaging/artifact.rb', line 320

def lookup(spec)
  @artifacts ||= {}
  @artifacts[to_spec(spec)]
end

.register(*tasks) ⇒ Object

:call-seq:

register(artifacts) => artifacts

Register an artifact task(s) for later lookup (see #lookup).



338
339
340
341
342
343
344
 
# File 'lib/buildr/packaging/artifact.rb', line 338

def register(*tasks)
  @artifacts ||= {}
  fail 'You can only register an artifact task, one of the arguments is not a Task that responds to to_spec' unless
    tasks.all? { |task| task.respond_to?(:to_spec) && task.respond_to?(:invoke) }
  tasks.each { |task| @artifacts[task.to_spec] = task }
  tasks
end

.to_hash(spec) ⇒ Object

:call-seq:

to_hash(spec_hash) => spec_hash
to_hash(spec_string) => spec_hash
to_hash(artifact) => spec_hash

Turn a spec into a hash. This method accepts a String, Hash or any object that responds to the method to_spec. There are several reasons to use this method:

  • You can pass anything that could possibly be a spec, and get a hash.

  • It will check that the spec includes the group identifier, artifact identifier and version number and set the file type, if missing.

  • It will always return a new specs hash.



357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
 
# File 'lib/buildr/packaging/artifact.rb', line 357

def to_hash(spec)
  if spec.respond_to?(:to_spec)
    to_hash spec.to_spec
  elsif Hash === spec
    rake_check_options spec, :id, :group, :type, :classifier, :version, :scope
    # Sanitize the hash and check it's valid.
    spec = ARTIFACT_ATTRIBUTES.inject({}) { |h, k| h[k] = spec[k].to_s if spec[k] ; h }
    fail "Missing group identifier for #{spec.inspect}" unless spec[:group]
    fail "Missing artifact identifier for #{spec.inspect}" unless spec[:id]
    fail "Missing version for #{spec.inspect}" unless spec[:version]
    spec[:type] = (spec[:type] || DEFAULT_TYPE).to_sym
    spec
  elsif String === spec
    group, id, type, version, *rest = spec.split(':').map { |part| part.empty? ? nil : part }
    unless rest.empty?
      # Optional classifier comes before version.
      classifier, version = version, rest.shift
      fail "Expecting <group:id:type:version> or <group:id:type:classifier:version>, found <#{spec}>" unless rest.empty?
    end
    to_hash :group=>group, :id=>id, :type=>type, :version=>version, :classifier=>classifier
  else
    fail 'Expecting a String, Hash or object that responds to to_spec'
  end
end

.to_spec(hash) ⇒ Object

:call-seq:

to_spec(spec_hash) => spec_string

Convert a hash back to a spec string. This method accepts a string, hash or any object that responds to to_spec.



387
388
389
390
391
392
 
# File 'lib/buildr/packaging/artifact.rb', line 387

def to_spec(hash)
  hash = to_hash(hash) unless Hash === hash
  version = ":#{hash[:version]}" if hash[:version]
  classifier = ":#{hash[:classifier]}" if hash[:classifier]
  "#{hash[:group]}:#{hash[:id]}:#{hash[:type] || DEFAULT_TYPE}#{classifier}#{version}"
end

Instance Method Details

#content(string = nil) ⇒ Object

:call-seq:

content(string) => self
content(Proc) => self

Use this when you want to install or upload an artifact from a given content, for example:

readme = artifact('com.example:readme:txt:1.0').content(<<-EOF
  Please visit our website at http://example.com/readme
<<EOF
install readme

If the argument is a Proc the it will be called when the artifact is written out. If the result is not a proc and not a string, it will be converted to a string using to_s



452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
 
# File 'lib/buildr/packaging/artifact.rb', line 452

def content(string = nil)
  unless string
    @content = @content.call if @content.is_a?(Proc)
    return @content
  end

  unless @content
    enhance do
      write name, self.content
    end

    class << self
      # Force overwriting target since we don't have source file
      # to check for timestamp modification
      def needed?
        true
      end
    end
  end
  @content = string
  pom.content pom_xml unless pom == self || pom.has_content?
  self
end

#from(path) ⇒ Object

:call-seq:

from(path) => self

Use this when you want to install or upload an artifact from a given file, for example:

test = artifact('group:id:jar:1.0').from('test.jar')
install test

See also Buildr#install and Buildr#upload.



430
431
432
433
434
435
436
437
438
 
# File 'lib/buildr/packaging/artifact.rb', line 430

def from(path)
  @from = path.is_a?(Rake::Task) ? path : File.expand_path(path.to_s)
  enhance [@from] do
    mkpath File.dirname(name)
    cp @from.to_s, name
  end
  pom.content pom_xml unless pom == self || pom.has_content?
  self
end