com.canoo.dolphin.BeanManager Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of dolphin-platform-rpm-common Show documentation
The Dolphin Platform is a framework that implements the presentation model pattern and provides amodern way to create enterprise applications. The Platform provides several client implementations that all canbe used in combination with a general sever API.
There is a newer version: 0.16.0
Show newest version
/*
 * Copyright 2015-2017 Canoo Engineering AG.
 *
 * 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 com.canoo.dolphin;

import com.canoo.dolphin.event.BeanAddedListener;
import com.canoo.platform.core.functional.Subscription;

import java.util.List;

/**
 * The {@link BeanManager} defined the low level API of the Dolphin Platform to create synchronized models. A model
 * instance that is created by using the bean manager will automatically synchronized between the client and server.
 * 

 * 

 * 
 * In the Dolphin Platform architecture an application is normally defined by several MVC groups with a server side
 * controller, a client side view and a synchronized presentation model. The {@link com.canoo.dolphin.BeanManager}
 * defines the basic mechanism to handle synchronized models and can be used in the MVC group to mutate the defined model
 * or as a standalone API to create any kind of synchronized model.
 * 

 * 

 * 
 * When using the MVC API of Dolphin Platform the lifecycle of the model is defined by the MVC group and the model
 * will automatically be removed when the MVC group is removed. If the {@link com.canoo.dolphin.BeanManager} is used as
 * standalone API the developer must handle the lifecycle of the models and removePresentationModel them by using the {@link com.canoo.dolphin.BeanManager}
 * All synchronized models must follow some specific rules that are described in the {@link com.canoo.dolphin.mapping.DolphinBean} annotation
 *
 * By using the default Spring or JavaEE implementation of the Dolphin platform the {@link com.canoo.dolphin.BeanManager}
 * will be provided as a managed bean and can be injected wherever the container allows injection.
 *
 * To create a new model the {@link com.canoo.dolphin.BeanManager} provides the {@link #create(Class)} method that is
 * defined as a factory method for any kind of model. A model should never be instantiated by hand because in that case
 * the model won't be synchronized between client and server. Here is an example how a model can be created:
 * 

 *  *     MyModel model = beanManager.create(MyModel.class);
 * 
 * 
 * 
 * The {@link com.canoo.dolphin.BeanManager} provides several methods to observe the creation and deletion of models.
 * One example is the {@link #onAdded(Class, com.canoo.dolphin.event.BeanAddedListener)} method. All the methods are
 * for using lambdas and therefore a handler can be easily added with only one line if code:
 * 

 *  *     beanManager.onAdded(MyModel.class, model -> System.out.println("Model of type MyModel added"));
 * 
 * 
 * There are no method to removePresentationModel registered handler from the {@link com.canoo.dolphin.BeanManager}. Here Dolphin Platform
 * implement an approach by using the Subscription Pattern: Each hander registration returns a {@link Subscription}
 * instance that provides the {@link Subscription#unsubscribe()} method to removePresentationModel the handler.
 * 
 * To deleta a synchronized model the {@link com.canoo.dolphin.BeanManager} provides several methods. Here a developer can
 * for example choose to delete a specific instance (see {@link #remove(Object)}) or all instances for a given type (see {@link #removeAll(Class)}).
 */
public interface BeanManager {

    /**
     * Creates a new instance of the given dolphin bean class that will automatically be synced with the client.
     * The given class must be defined as a dolphin bean
     *
     * @param beanClass the bean class
     * @param        bean type
     * @return the new bean instance
     */
     T create(Class beanClass);

    /**
     * Returns a list of all dolphin managed beans of the given type / class
     *
     * @param beanClass the bean type
     * @param        the bean type
     * @return a list of all managed beans of the type
     */
    @Deprecated
     List findAll(Class beanClass);

    /**
     * Subscribe a listener to all bean creation events for a specific class. A listener that is added to a client side
     * {@link BeanManager} will only fire events for beans that where created on the server side and vice versa. This means that the listener
     * isn't fired for a bean that was created by the same {@link BeanManager}.
     *
     * @param beanClass the class for which creation events should be received
     * @param listener the listener which receives the creation-events
     * @param  the bean type
     * @return the (@link com.canoo.platform.core.functional.Subscription} that can be used to unsubscribe the listener
     */
    @Deprecated
     Subscription onAdded(Class beanClass, BeanAddedListener listener);


}