net.smartcosmos.client.objects.relationship.IRelationshipClient Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of java-client Show documentation
Provides a thin client wrapper for accessing the SMART COSMOS platform web services
The newest version!
package net.smartcosmos.client.objects.relationship;

/*
 * *#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*
 * SMART COSMOS Platform Client
 * ===============================================================================
 * Copyright (C) 2013 - 2014 SMARTRAC Technology Fletcher, Inc.
 * ===============================================================================
 * 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.
 * #*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#
 */

import net.smartcosmos.client.connectivity.ServiceException;
import net.smartcosmos.client.impl.IDeleteableBaseClient;
import net.smartcosmos.client.impl.IUpsertableBaseClient;
import net.smartcosmos.model.base.EntityReferenceType;
import net.smartcosmos.objects.model.context.IRelationship;
import net.smartcosmos.util.json.ViewType;

import java.util.Collection;

/**
 * Defines, deletes, or queries for {@link net.smartcosmos.objects.model.context.IRelationship} instances.
 * 
 * A relationship is a binary concept that either exists or doesn't. For example, a specific Driver object cannot
 * "LIKE" a specific Car object multiple times. The driver "LIKE"s the Car, or does not "LIKE" the car. As documented
 * by {@link net.smartcosmos.client.impl.IUpsertableBaseClient}, relationship creation is idempotent; no matter how
 * many times the relationship is defined, it is guaranteed to only exist once in the database.
 */
public interface IRelationshipClient extends IUpsertableBaseClient, IDeleteableBaseClient
{
    /**
     * Retrieves all of the documented relationships between two specific entities.
     * 

     * Each {@link net.smartcosmos.objects.model.context.IRelationship} will be serialized using a
     * {@link net.smartcosmos.util.json.ViewType#Standard} view.
     *
     * @param entityReferenceType        owner/parent entity reference type
     * @param referenceUrn               owner/parent reference URN
     * @param relatedEntityReferenceType child entity reference type
     * @param relatedReferenceUrn        child entity reference URN
     * @return Non-null collection of matching relationships; collection may have a size of 0 to indicate no matches
     * @throws ServiceException
     */
    Collection findAllBetweenTwoEntities(EntityReferenceType entityReferenceType,
                                                        String referenceUrn,
                                                        EntityReferenceType relatedEntityReferenceType,
                                                        String relatedReferenceUrn) throws ServiceException;

    /**
     * Retrieves all of the documented relationships between two specific entities.
     * 

     * Each {@link net.smartcosmos.objects.model.context.IRelationship} will be serialized using the specified field
     * verbosity.
     *
     * @param entityReferenceType        owner/parent entity reference type
     * @param referenceUrn               owner/parent reference URN
     * @param relatedEntityReferenceType child entity reference type
     * @param relatedReferenceUrn        child entity reference URN
     * @param viewType                   Field verbosity
     * @return Non-null collection of matching relationships; collection may have a size of 0 to indicate no matches
     * @throws ServiceException
     */
    Collection findAllBetweenTwoEntities(EntityReferenceType entityReferenceType,
                                                        String referenceUrn,
                                                        EntityReferenceType relatedEntityReferenceType,
                                                        String relatedReferenceUrn,
                                                        ViewType viewType) throws ServiceException;

    /**
     * Retrieves a very specific relationship between two specific entities, if it exists.
     * 

     * Each {@link net.smartcosmos.objects.model.context.IRelationship} will be serialized using a
     * {@link net.smartcosmos.util.json.ViewType#Standard} view.
     *
     * @param entityReferenceType        owner/parent entity reference type
     * @param referenceUrn               owner/parent reference URN
     * @param relatedEntityReferenceType child entity reference type
     * @param relatedReferenceUrn        child entity reference URN
     * @return Non-null collection of matching relationships; collection may have a size of 0 to indicate no matches
     * @throws ServiceException
     */
    IRelationship findSpecificRelationship(EntityReferenceType entityReferenceType, String referenceUrn,
                                           EntityReferenceType relatedEntityReferenceType,
                                           String relatedReferenceUrn,
                                           String relationshipType) throws ServiceException;

    /**
     * Retrieves a very specific relationship between two specific entities, if it exists.
     * 

     * The {@link net.smartcosmos.objects.model.context.IRelationship} will be serialized using the specified field
     * verbosity.
     *
     * @param entityReferenceType        owner/parent entity reference type
     * @param referenceUrn               owner/parent reference URN
     * @param relatedEntityReferenceType child entity reference type
     * @param relatedReferenceUrn        child entity reference URN
     * @param relationshipType           case-sensitive name of the relationship
     * @param viewType                   Field verbosity
     * @return Non-null collection of matching relationships; collection may have a size of 0 to indicate no matches
     * @throws ServiceException
     */
    IRelationship findSpecificRelationship(EntityReferenceType entityReferenceType,
                                           String referenceUrn,
                                           EntityReferenceType relatedEntityReferenceType,
                                           String relatedReferenceUrn,
                                           String relationshipType,
                                           ViewType viewType) throws ServiceException;

    /**
     * Retrieves all child entities that the specified entity has the specified relationship type with.
     * 

     * Each {@link net.smartcosmos.objects.model.context.IRelationship} will be serialized using a
     * {@link net.smartcosmos.util.json.ViewType#Standard} view.
     * 

     * One can use this query to answer the question "Tell me all of the relationships my Vehicle has, which might
     * be two: an {@link net.smartcosmos.objects.model.context.IObject} that is the "garage" where the vehicle is worked
     * on and another {@link net.smartcosmos.objects.model.context.IObject} that is the "owner" of the vehicle. Compare
     * this result with the collection returned from
     * {@link #findReverseRelationships(net.smartcosmos.model.base.EntityReferenceType, String, String)}.
     *
     * @param entityReferenceType owner/parent entity reference type
     * @param referenceUrn        owner/parent reference URN
     * @param relationshipType    case-sensitive name of the relationship
     * @return Non-null collection of matching relationships; collection may have a size of 0 to indicate no matches
     * @throws ServiceException
     */
    Collection findRelationships(EntityReferenceType entityReferenceType,
                                                String referenceUrn,
                                                String relationshipType) throws ServiceException;

    /**
     * Retrieves all child entities that the specified entity has the specified relationship type with.
     * 

     * Each {@link net.smartcosmos.objects.model.context.IRelationship} will be serialized using the specified field
     * verbosity.
     * 

     * One can use this query to answer the question "Tell me all of the relationships my Vehicle has, which might
     * be two: an {@link net.smartcosmos.objects.model.context.IObject} that is the "garage" where the vehicle is worked
     * on and another {@link net.smartcosmos.objects.model.context.IObject} that is the "owner" of the vehicle. Compare
     * this result with the collection returned from
     * {@link #findReverseRelationships(net.smartcosmos.model.base.EntityReferenceType, String, String)}.
     *
     * @param entityReferenceType owner/parent entity reference type
     * @param referenceUrn        owner/parent reference URN
     * @param relationshipType    case-sensitive name of the relationship
     * @param viewType            Field verbosity
     * @return Non-null collection of matching relationships; collection may have a size of 0 to indicate no matches
     * @throws ServiceException
     */
    Collection findRelationships(EntityReferenceType entityReferenceType,
                                                String referenceUrn,
                                                String relationshipType,
                                                ViewType viewType) throws ServiceException;

    /**
     * Retrieves all owner/parent entities that the specified entity has the specified relationship type with.
     * 

     * Each {@link net.smartcosmos.objects.model.context.IRelationship} will be serialized using a
     * {@link net.smartcosmos.util.json.ViewType#Standard} view.
     * 

     * One can use this query to answer the question "Tell me all of the parent relationships to my "garage",
     * which might be four: an {@link net.smartcosmos.objects.model.context.IObject} for each "Vehicle" that has been to
     * the garage. Compare this result with the collection returned from
     * {@link #findRelationships(net.smartcosmos.model.base.EntityReferenceType, String, String)}.
     *
     * @param entityReferenceType child entity reference type
     * @param referenceUrn        child reference URN
     * @param relationshipType    case-sensitive name of the relationship
     * @return Non-null collection of matching relationships; collection may have a size of 0 to indicate no matches
     * @throws ServiceException
     */
    Collection findReverseRelationships(EntityReferenceType entityReferenceType,
                                                       String referenceUrn,
                                                       String relationshipType) throws ServiceException;

    /**
     * Retrieves all owner/parent entities that the specified entity has the specified relationship type with.
     * 

     * Each {@link net.smartcosmos.objects.model.context.IRelationship} will be serialized using the specified field
     * verbosity.
     * 
     * One can use this query to answer the question "Tell me all of the parent relationships to my "garage", which
     * might be four: an {@link net.smartcosmos.objects.model.context.IObject} for each "Vehicle" that has been to the
     * garage. Compare this result with the collection returned from
     * {@link #findRelationships(net.smartcosmos.model.base.EntityReferenceType, String, String)}.
     *
     * @param entityReferenceType child entity reference type
     * @param referenceUrn        child reference URN
     * @param relationshipType    case-sensitive name of the relationship
     * @param viewType            Field verbosity
     * @return Non-null collection of matching relationships; collection may have a size of 0 to indicate no matches
     * @throws ServiceException
     */
    Collection findReverseRelationships(EntityReferenceType entityReferenceType,
                                                       String referenceUrn,
                                                       String relationshipType,
                                                       ViewType viewType) throws ServiceException;
}