com.asakusafw.vocabulary.model

Annotation Type Once

@Target(value=PARAMETER)
 @Retention(value=RUNTIME)
 @Documented
public @interface Once

An annotation represents which the annotated element will be used only once. This can appear with the following elements:

• Input parameter of CoGroup and GroupSort operator methods. A parameter with this annotation represents that elements in the parameter must be accessed only once. The parameter must be defined as Iterable type, and clients can invoke its iterator() only once in the operator method. If clients invoke the method more than once, it MAY raise an exception. Typically, the annotated parameter is used with for statement like as following:

  
  @CoGroup
  public void iterate(@Key(...) @Once Iterable<Hoge> input, Result<Hoge> result) {
      for (Hoge hoge : input) {
          ...
      }
  }
  

  With this annotation, obtaining elements in the sequence will change the old object from the sequence. For example, the operations are not guaranteed in the following case:

  
  @CoGroup
  public void invalid(@Key(...) @Once Iterable<Hoge> input, Result<Hoge> result) {
      Iterator<Hoge> iter = input.iterator();
      Hoge a = iter.next();
      Hoge b = iter.next(); // this operation may break out contents of 'a'
      ...
  }
  

  In such the case, application developers should create a copy of the object:

  
  final Hoge a = new Hoge();
  final Hoge b = new Hoge();
  
  @CoGroup
  public void invalid(@Key(...) @Once Iterable<Hoge> input, Result<Hoge> result) {
      a.copyFrom(iter.next()); // create a copy
      b.copyFrom(iter.next());
      ...
  }
  

Since:

0.9.1