001/*
002 * file CcHyperlink.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM 
006 * com.ibm.rational.wvcm.stp.cc.CcHyperlink
007 *
008 * (C) Copyright IBM Corporation 2007, 2014.  All Rights Reserved.
009 * Note to U.S. Government Users Restricted Rights:  Use, duplication or 
010 * disclosure restricted by GSA ADP  Schedule Contract with IBM Corp.
011 */
012package com.ibm.rational.wvcm.stp.cc;
013
014import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
015
016import javax.wvcm.WvcmException;
017import javax.wvcm.PropertyNameList.PropertyName;
018
019/**
020 * A proxy for a ClearCase hyperlink object.
021 * <p>
022 * Conceptually, a hyperlink is an arrow from one VOB-database object (version, branch, element, 
023 * VOB symbolic link or VOB) to another.  A merge arrow is a special kind of hyperlink.
024 * </p>
025 * <p>
026 * For more information about hyperlinks, see the ClearCase "Guide to Managing Software Projects"
027 * manual, and the cleartool man page "mkhlink".
028 * </p>
029 */
030public interface CcHyperlink extends CcVobResource
031{
032    /**
033     * The resource at the "from" end of the hyperlink
034     */
035    PropertyName<CcResource> FROM_RESOURCE =
036        new PropertyName<CcResource>(PROPERTY_NAMESPACE,
037                                     "hlink-from-resource");
038   
039    /**
040     * Get the value of this hyperlink instance's {@link #FROM_RESOURCE} property.
041     * 
042     * @return resource hyperlink instance points from
043     * @throws WvcmException
044     *             if this proxy doesn't define a value for this property or 
045     *             the resource is unavailable/does not exist
046     */
047    CcResource getFromResource() throws WvcmException;
048
049    /**
050     * The text associated with the "from" end of the hyperlink.
051     */
052    PropertyName<String> FROM_TEXT =
053        new PropertyName<String>(PROPERTY_NAMESPACE,
054                                     "hlink-from-text");
055    
056    /**
057     * Get the value of this hyperlink instance's {@link #FROM_TEXT} property.
058     * 
059     * @return String containing text associated with the "from" end of the hyperlink.
060     *         Will be <code>null</code> if no text was specified during hyperlink creation.
061     * @throws WvcmException
062     *             if this proxy doesn't define a value for this property or 
063     *             the resource is unavailable/does not exist
064     */
065    String getFromText() throws WvcmException;
066    
067    /**
068     * The resource at the "to" end of the hyperlink
069     */
070    PropertyName<CcResource> TO_RESOURCE =
071        new PropertyName<CcResource>(PROPERTY_NAMESPACE,
072                                     "hlink-to-resource");
073   
074    /**
075     * Get the value of this hyperlink instance's {@link #TO_RESOURCE} property.
076     * 
077     * @return resource hyperlink instance points to, or null if single-ended hyperlink
078     * @throws WvcmException
079     *             if this proxy doesn't define a value for this property or 
080     *             the resource is unavailable/does not exist
081     */
082    CcResource getToResource() throws WvcmException;
083
084    /**
085     * The text associated with the "to" end of the hyperlink.
086     */
087    PropertyName<String> TO_TEXT =
088        new PropertyName<String>(PROPERTY_NAMESPACE,
089                                     "hlink-to-text");
090    
091    /**
092     * Get the value of this hyperlink instance's {@link #TO_TEXT} property.
093     * 
094     * @return String containing text associated with the "to" end of the hyperlink.
095     *         Will be <code>null</code> if no text was specified during hyperlink creation.
096     * @throws WvcmException
097     *             if this proxy doesn't define a value for this property or 
098     *             the resource is unavailable/does not exist
099     */
100    String getToText() throws WvcmException;
101    
102    /**
103     * The hyperlink type of which this hyperlink is an instance.
104     */
105    PropertyName<CcHyperlinkType> TYPE =
106        new PropertyName<CcHyperlinkType>(PROPERTY_NAMESPACE,
107                                          "hlink-type");
108
109    /**
110     * Get the value of this hyperlink instance's {@link #TYPE} property.
111     * 
112     * @return hyperlink instance's hyperlink type
113     * @throws WvcmException
114     *             if this proxy doesn't define a value for this property.
115     */
116    CcHyperlinkType getType() throws WvcmException;
117
118}