Topic
  • 3 replies
  • Latest Post - ‏2013-10-28T01:43:21Z by Scott_Longwell
SystemAdmin
SystemAdmin
1086 Posts

Pinned topic How to identify the API's easily

‏2013-02-25T06:03:52Z |
Hi All,

I am sorry if my question is too vague.

I am having to develop some plugins using the API's. I was looking at Javadoc and the samples. Once I go through some implemenation code, I am having a difficulty in rememberinng or getting confused amongst various similar interfaces.

For example,
I have used the following clases/interfaces for my implementation but, at the end, I dont remember/confused on how they differ and what functionality each provides.

All the different Factory's:
IPhysicalResourceFactory vs PhysicalResourceFactoryFactory vs PhysicalSystemRegistryFactory vs ZosphysicalFactory vs ZosfactoryFactory

All the different Physical's(same wrt Logical's):
ZOSPhysicalResource vs IPhysicalResource vs ZOSResourceIdentifier vs ZOSPhysicalResourceFinder

IOSImage vs ZOSSystemImageImpl

IPhysicalFile vs ZOSSequentialDataSet vs ZOSDataSet

I guess i was hoping to find any documentation/way to tell how the packages are classified. For example what will we find different between, com.ibm.ftt.resources.core.physicalfactory versus com.ibm.ftt.resources.zos.zosphysical packages, they are both physicals but one is core versus zos.

I was wondering what is the best way to get clarity on these API's? Is there any analogy that would help easily find the API, what we are looking for? Any documentation on the naming convensions followed for categorizing the way it is will be of great help.

Thank you!
Ravikanth Chavali
Updated on 2013-02-26T18:10:08Z at 2013-02-26T18:10:08Z by Scott_Longwell
  • Scott_Longwell
    Scott_Longwell
    6 Posts

    Re: How to identify the API's easily

    ‏2013-02-26T18:10:08Z  
    Hi Ravi,

    Sorry you are having trouble parsing the JavaDoc. I will try to clear up some of your questions.

    1) "Any documentation on the naming conventions followed for categorizing the way it is will be of great help". "Logical" resources refer to resources that have are associated with RDz projects. Since you can add the same resource to more than 1 subproject, there can be multiple "logical" resources corresponding to a given "physical" resource. Logical resources always refer back to a physical resource. Classes with names starting with "ZOS" have characteristics specific to MVS (vs z/OS Unix, AIX etc) and generally extend more general classes e.g. ZOSSystemImage extends IOSImage.

    2) "ZOSPhysicalResource vs IPhysicalResource vs ZOSResourceIdentifier vs ZOSPhysicalResourceFinder". ZOSPhysicalResource does not exist. I think you mean ZOSResource which is an MVS specialization of IPhysicalResource. See my answer to 1) above. ZOSPhysicalResourceFinder is a utility class for finding a ZOSResource by passing it a ZOSResourceIdentifier. This allows you to start with things like resource name, location, etc. and end up with a live object. This seems clear to me in the JavaDoc. Is there something in there that does not make sense?

    3) "IOSImage vs ZOSSystemImageImpl" See 1) above except that ZOSSystemImageImpl is an implementation class that is not part of the published API (is not included in the JavaDoc) and contains private methods which are not guaranteed to be stable over time. You should be using the ZOSSystemImage interface. Let us know if the impl class has a method you need and can't find in the interface.

    4) "IPhysicalFile vs ZOSSequentialDataSet vs ZOSDataSet" From the JavaDoc you can see that ZOSSequentialDataSet extends ZOSDataSet and IPhysicalFile so it is a specialization of both a dataset (MVS specific) and a file. Does that answer the question?

    5) "IPhysicalResourceFactory vs PhysicalResourceFactoryFactory vs PhysicalSystemRegistryFactory vs ZosphysicalFactory vs ZosfactoryFactory" These names are admittedly confusing and have their roots back in the early days of the product when we were using EMF to generate some of our code. Your best bet here is to use the included samples to see how each is used e.g. PhysicalResourceFactoryFactory is used to obtain an IPhysicalResourceFactory in the AllocatePDSAction sample.

    Hope this helps.
  • RavikanthChavali
    RavikanthChavali
    16 Posts

    Re: How to identify the API's easily

    ‏2013-09-29T03:56:49Z  
    Hi Ravi,

    Sorry you are having trouble parsing the JavaDoc. I will try to clear up some of your questions.

    1) "Any documentation on the naming conventions followed for categorizing the way it is will be of great help". "Logical" resources refer to resources that have are associated with RDz projects. Since you can add the same resource to more than 1 subproject, there can be multiple "logical" resources corresponding to a given "physical" resource. Logical resources always refer back to a physical resource. Classes with names starting with "ZOS" have characteristics specific to MVS (vs z/OS Unix, AIX etc) and generally extend more general classes e.g. ZOSSystemImage extends IOSImage.

    2) "ZOSPhysicalResource vs IPhysicalResource vs ZOSResourceIdentifier vs ZOSPhysicalResourceFinder". ZOSPhysicalResource does not exist. I think you mean ZOSResource which is an MVS specialization of IPhysicalResource. See my answer to 1) above. ZOSPhysicalResourceFinder is a utility class for finding a ZOSResource by passing it a ZOSResourceIdentifier. This allows you to start with things like resource name, location, etc. and end up with a live object. This seems clear to me in the JavaDoc. Is there something in there that does not make sense?

    3) "IOSImage vs ZOSSystemImageImpl" See 1) above except that ZOSSystemImageImpl is an implementation class that is not part of the published API (is not included in the JavaDoc) and contains private methods which are not guaranteed to be stable over time. You should be using the ZOSSystemImage interface. Let us know if the impl class has a method you need and can't find in the interface.

    4) "IPhysicalFile vs ZOSSequentialDataSet vs ZOSDataSet" From the JavaDoc you can see that ZOSSequentialDataSet extends ZOSDataSet and IPhysicalFile so it is a specialization of both a dataset (MVS specific) and a file. Does that answer the question?

    5) "IPhysicalResourceFactory vs PhysicalResourceFactoryFactory vs PhysicalSystemRegistryFactory vs ZosphysicalFactory vs ZosfactoryFactory" These names are admittedly confusing and have their roots back in the early days of the product when we were using EMF to generate some of our code. Your best bet here is to use the included samples to see how each is used e.g. PhysicalResourceFactoryFactory is used to obtain an IPhysicalResourceFactory in the AllocatePDSAction sample.

    Hope this helps.

    Scott, Thank you so much for the detailed explanation. I really appreciate the detail and am sure it has reached the larger audience and helped community understand better as well.

    I am now clear on, Logical versus Physical and how "names starting with "ZOS" have characteristics specific to MVS (vs z/OS Unix, AIX etc). Your explanation on "ZOSPhysicalResourceFinder is a utility class for finding a ZOSResource by passing it a ZOSResourceIdentifier. This allows you to start with things like resource name, location, etc. and end up with a live object." made a clear distinguistion among those three and also when you spelled it out "ZOSSequentialDataSet extends ZOSDataSet and IPhysicalFile so it is a specialization of both a dataset (MVS specific) and a file" I found it very helpful.

    All, Any additional clarifications on the following will be helpful?

    Under core.logical package, I am unclear with their remote counter parts. I would think Remote is RemoteSystems(z/OS, Linux, etc) in RSE. But the below javadoc snapshot shows that remote project is a collection of logical sub projects.

    1. What is the significance of having "remote" when we have "logical" versus "physical"? Is "remote" just an interface to handshake between logicals & physicals?
    2. What does a remote resource (IRemoteResource), remote project(IRemoteProject) & remote subproject(IRemoteSubProject) refer to ? How about their physical existance on Remote system?

    IRemoteProject

    A remote project, which is a collection of ILogicalSubProjects.

    IRemoteResource

    Abstract interface for a remote resource.

    IRemoteSubProject

    A remote subproject.

    
    3. What does reference (IResource 
    Reference/ZOSResource 
    Reference and ISystem 
    Reference/ZOSSystem 
    Reference) provide? Example, to validate IPhysicalResource why do we have to first validate if it is of type IResourceReference then typecase and then from the resultant again validate and typecase for IPhysicalResource. Dont mean to be picky but i am refering to one of samples "
    CopyPhysicalResourceAction".  Why should we do this instead directly check/validate for IPhysical resource. In AllocatePDSAction sample we pass the ZOSSystem
    Reference and then cast it to ZOSSystemImage to get the ZOSCatalog. Why was it chose to pass the Reference object instead of the Image itself?
    

    I like the way IPhysicalResource is described in the javadoc but couldn't find similar analogy for ILogical* or IRemote*. If I were to draw a analogy, I thought(Please correct me if I am wrong.)

    ILogicalResource(refers every artifact under zOS Projects view including PG associated) à IRemoteResource (extends ILogical and provides ProjectState online/offline/exists/system/validatePhysical) à LZOSResource(extends IRemote and provide ResourceState) and

    IPhysicalResource(refers to physical model in RSE Local/Linux/zOS)à ZOSResource(refers MVS files) à ZOSDataset(refers MVS files and provdes FileState) 

    "The IPhysicalResource has two generic subinterfaces. The IPhysicalFile represents a physical resource that holds data, and the IPhysicalContainer contains other physical resources"  and on the other hand ILogicalFile just represents PDSMember and Sequential file but not VSAMs and GDGs.

    4. Does VSAMs and GDGs have their Logical personalities?

    5. Do you have any heirarchy diagram with these classes and interfaces? The tree view helps but just incase you have anything better.

    Thanks,
    Ravikanth Chavali

     
    Updated on 2013-10-16T00:54:07Z at 2013-10-16T00:54:07Z by RavikanthChavali
  • Scott_Longwell
    Scott_Longwell
    6 Posts

    Re: How to identify the API's easily

    ‏2013-10-28T01:43:21Z  

    Scott, Thank you so much for the detailed explanation. I really appreciate the detail and am sure it has reached the larger audience and helped community understand better as well.

    I am now clear on, Logical versus Physical and how "names starting with "ZOS" have characteristics specific to MVS (vs z/OS Unix, AIX etc). Your explanation on "ZOSPhysicalResourceFinder is a utility class for finding a ZOSResource by passing it a ZOSResourceIdentifier. This allows you to start with things like resource name, location, etc. and end up with a live object." made a clear distinguistion among those three and also when you spelled it out "ZOSSequentialDataSet extends ZOSDataSet and IPhysicalFile so it is a specialization of both a dataset (MVS specific) and a file" I found it very helpful.

    All, Any additional clarifications on the following will be helpful?

    Under core.logical package, I am unclear with their remote counter parts. I would think Remote is RemoteSystems(z/OS, Linux, etc) in RSE. But the below javadoc snapshot shows that remote project is a collection of logical sub projects.

    1. What is the significance of having "remote" when we have "logical" versus "physical"? Is "remote" just an interface to handshake between logicals & physicals?
    2. What does a remote resource (IRemoteResource), remote project(IRemoteProject) & remote subproject(IRemoteSubProject) refer to ? How about their physical existance on Remote system?

    IRemoteProject

    A remote project, which is a collection of ILogicalSubProjects.

    IRemoteResource

    Abstract interface for a remote resource.

    IRemoteSubProject

    A remote subproject.

    <pre dir="ltr" style="font-size: 13px; color: rgb(0,0,0); margin-left: 40px"> 3. What does reference (IResource Reference/ZOSResource Reference and ISystem Reference/ZOSSystem Reference) provide? Example, to validate IPhysicalResource why do we have to first validate if it is of type IResourceReference then typecase and then from the resultant again validate and typecase for IPhysicalResource. Dont mean to be picky but i am refering to one of samples " CopyPhysicalResourceAction". Why should we do this instead directly check/validate for IPhysical resource. In AllocatePDSAction sample we pass the ZOSSystem Reference and then cast it to ZOSSystemImage to get the ZOSCatalog. Why was it chose to pass the Reference object instead of the Image itself? </pre>

    I like the way IPhysicalResource is described in the javadoc but couldn't find similar analogy for ILogical* or IRemote*. If I were to draw a analogy, I thought(Please correct me if I am wrong.)

    ILogicalResource(refers every artifact under zOS Projects view including PG associated) à IRemoteResource (extends ILogical and provides ProjectState online/offline/exists/system/validatePhysical) à LZOSResource(extends IRemote and provide ResourceState) and

    IPhysicalResource(refers to physical model in RSE Local/Linux/zOS)à ZOSResource(refers MVS files) à ZOSDataset(refers MVS files and provdes FileState) 

    "The IPhysicalResource has two generic subinterfaces. The IPhysicalFile represents a physical resource that holds data, and the IPhysicalContainer contains other physical resources"  and on the other hand ILogicalFile just represents PDSMember and Sequential file but not VSAMs and GDGs.

    4. Does VSAMs and GDGs have their Logical personalities?

    5. Do you have any heirarchy diagram with these classes and interfaces? The tree view helps but just incase you have anything better.

    Thanks,
    Ravikanth Chavali

     
    Hi Ravi,
     
    Here are some attempts to answer your questions.
     
    1) "What is the significance of having "remote" when we have "logical" versus "physical"? Is "remote" just an interface to handshake between logicals & physicals?"  We have an IRemoteResource interface because one of the interfaces that extends ILogicalResource is LResource which relates to a local Eclipse IResource in the same way that LZOSResource (logical) relates to a ZOSPhysicalResource (physical).  If you see a local project in the z/OS Projects view, the objects making up that project are LResources.  The methods that LZOSResource inherits from IRemoteResource (e.g. getSystem() do not make sense for local resources.  We also didn't want to put them at the LZOSResource level because we had something called LHFSResources that were supposed to represent z/OS Unix files.  That never actually came to be, but IRemoteResource remains.
     
    2) "What does a remote resource (IRemoteResource), remote project(IRemoteProject) & remote subproject(IRemoteSubProject) refer to ? How about their physical existance on Remote system?"
    Those classes all relate to the z/OS Projects view and have no counterparts in the Remote Systems view.  Projects contain one or more subprojects.  Subprojects have an association with a single remote system and contain logical resources on that system.  Each logical resource in turn has a physical counterpart that can be found in the Remote Systems view.  A single physical resource can be added to multiple logical subprojects so logical to physical can be a many to one relationship.
     
    3)  "What does reference... (ZOSResourceReference) ... provide? Example, to validate IPhysicalResource why do we have to first validate if it is of type IResourceReference then typecase and then from the resultant again validate and typecase for IPhysicalResource."
    Notice that you need to call ZOSResourceReference.getReferent() to obtain the ZOSResource.  This is because we did not want to expose the actual object type displayed in Remote Systems view and wrapping it in a ZOSResoruceReference was a way to keep it out of our API.  Why?  Because the Remote Resource API is guaranteed to be stable over time which we could not claim for the underlying objects.  So if you stick to the Remote Resource API, you should be protected from changes to our underlying infrastructure.
     
    4) "Does VSAMs and GDGs have their Logical personalities?"
    VSAM datasets have no logical counterpart.  You can add a GDS in a GDG to a subproject and perform any operations available for a data set, but you cannot add a GDG as a group to a subproject.
     
    5) "Do you have any heirarchy diagram with these classes and interfaces? The tree view helps but just incase you have anything better." 
     
    Scott