What to call factory-like (java) methods used with immutable objects

Question

When creating classes for "immutable objects" immutable meaning that state of instances can not be changed; all fields assigned in constructor) in Java (and similar languages), it is sometimes useful to still allow creation of modified instances. That is, using an instance as base, and creating a new instance that differs by just one property value; other values coming from the base instance. To give a simple example, one could have class like:

public class Circle {
  final double x, y; // location
  final double radius;

  public Circle(double x, double y, double r) {
    this.x = x;
    this.y = y;
    this.r = r;
  }

  // method for creating a new instance, moved in x-axis by specified amount
  public Circle withOffset(double deltaX) {
    return new Circle(x+deltaX, y, radius);
  }
}

So: what should method "withOffset" be called? (note: NOT what its name ought to be -- but what is this class of methods called). Technically it is kind of a factory method, but somehow that does not seem quite right to me, since often factories are just given basic properties (and are either static methods, or are not members of the result type but factory type).

So I am guessing there should be a better term for such methods. Since these methods can be used to implement "fluent interface", maybe they could be "fluent factory methods"? Better suggestions?

EDIT: as suggested by one of answers, java.math.BigDecimal is a good example with its 'add', 'subtract' (etc) methods.

Also: I noticed that there's this question (by Jon Skeet no less) that is sort of related (although it asks about specific name for method)

EDIT, MAY-2014: My current favorite is mutant factory, FWIW.

Answer 1

I call those types of methods "copy methods".

While the clone() method creates an exact copy, a copy method makes a copy of an instance, usually with an implied or explicit variation. For example, String#toUpperCase() would be a copy method of the immutable String class - it copies an instance with a variation: it upcases all the letters.

I would consider withOffset() method in your example to be a similar copy method.

I don't know of any references that document the term "copy method". I'm borrowing the term "copy" from its use in C++: copy constructors and the "copy" naming guideline from the Taligent Coding Standards (more info).

---

As for the term "fluent factory methods", I don't know why "fluent" would make a difference, since a "fluent interface" is just an API style (separate from the builder pattern). If the term "factory method" doesn't apply here, I don't see how calling it a "fluent factory method" makes it apply any better.

Answer 2

Hrm … it creates mutated versions of the object … maybe we should call it a mutant factory? :-)