001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.marshall;
018
019import static java.lang.annotation.ElementType.*;
020import static java.lang.annotation.RetentionPolicy.*;
021
022import java.lang.annotation.*;
023
024/**
025 * Identifies the exact static factory method to use for creating an instance of a POJO from a string.
026 *
027 * <p>
028 * By default, {@link ClassMeta#newInstanceFromString(Object,String)} looks for a static method matching one of a
029 * fixed set of conventional names (<c>fromString</c>, <c>fromValue</c>, <c>valueOf</c>, <c>parse</c>,
030 * <c>parseString</c>, <c>forName</c>, <c>forString</c>) that takes a single {@link String} argument and returns an
031 * instance of the class, falling back to a single-{@link String}-arg constructor if none is found.
032 *
033 * <p>
034 * This annotation lets you opt out of that name-based guessing and explicitly name the static factory method to use,
035 * which is useful for classes whose factory method doesn't match any of the conventional names (e.g. <c>of</c> or
036 * <c>create</c>).
037 *
038 * <p>
039 * The annotated method must be <jk>static</jk>, return an instance of the class (or a subtype), and take exactly one
040 * {@link String} argument.
041 *
042 * <h5 class='figure'>Example:</h5>
043 * <p class='bjava'>
044 *    <ja>@StringCtor</ja>(<js>"of"</js>)
045 *    <jk>public class</jk> MyClass {
046 *
047 *       <jk>public static</jk> MyClass of(String <jv>value</jv>) {
048 *          <jk>return new</jk> MyClass(<jv>value</jv>);
049 *       }
050 *
051 *       ...
052 *    }
053 * </p>
054 *
055 * <h5 class='section'>See Also:</h5><ul>
056 *    <li class='jm'>{@link ClassMeta#newInstanceFromString(Object,String)}
057 * </ul>
058 *
059 * @since 9.2.0
060 */
061@Documented
062@Target(TYPE)
063@Retention(RUNTIME)
064@Inherited
065public @interface StringCtor {
066
067   /**
068    * The name of the static factory method to use for string-convertibility.
069    *
070    * <p>
071    * The named method must be <jk>static</jk>, return an instance of the annotated class, and take exactly one
072    * {@link String} argument.
073    *
074    * @return The annotation value.
075    */
076   String value();
077}