/*
 * Copyright 2009 Michael Burton
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
package roboguice.inject;

import roboguice.inject.ExtrasListener.ExtrasMembersInjector;

import com.google.inject.Injector;
import com.google.inject.Singleton;

/**
 * An object capable of providing objects of type {@code TO}, using extras of
 * type {@code FROM}.<br />
 * <br />
 * Converters enable you to convert Android Extras to complex objects. For
 * instance, sending a long timestamp as an extra, and getting a Date injected.<br />
 * <br />
 * Once you have created an {@link ExtraConverter} implementation, you should
 * bind it in your module configuration. Usage example: {@code bind(new
 * TypeLiteral<ExtraConverter<Long, Date>>() ).to(DateExtraConverter.class);}<br />
 * <br />
 * Usage in your components is as simple as : {@code
 * \@InjectExtra("timestampExtra") protected Date date; } <br />
 * <br />
 * You will usually want your converters to be singletons, so you should
 * annotate them with {@link Singleton}.<br />
 * <br />
 * Please notice that the context in which the bean that gets the extra injected
 * is scoped should implements {@link InjectorProvider} to get the convert
 * mechanism to work. This is because the {@link ExtrasMembersInjector} need an
 * {@link Injector} to get an {@link ExtraConverter} instance.
 * 
 * @param <FROM>
 * @param <TO>
 * 
 * @author Pierre-Yves Ricau (py.ricau+roboguice@gmail.com)
 */
public interface ExtraConverter<FROM, TO> {
    /**
     * Converts an instance of FROM to an instances of TO. May return null.
     *
     * @param from
     *            The extra value to be converted.
     * @return The converted object that will be injected.
     */
    TO convert(FROM from);
}